Events API

The Events API lets you query security events collected from your UniFi ecosystem. Use it to build dashboards, export data, or integrate with external systems.

Note

Events API endpoints require the events:read scope. Submitting custom events requires events:write.

List Events

GET /v1/events

Retrieve a paginated list of security events.

Parameter Type Required Description
page integer Optional Page number (default: 1)
per_page integer Optional Results per page, max 100 (default: 50)
after string Optional Cursor for cursor-based pagination
source string Optional Filter by source: unifi_network, unifi_protect, unifi_access, unifi_talk
severity string Optional Filter by severity: critical, high, medium, low, info
type string Optional Filter by event type (e.g., login_failure, motion, access_granted)
from ISO 8601 Optional Start of time range
to ISO 8601 Optional End of time range
search string Optional Full-text search across event fields
Example Request 

curl -H "Authorization: Bearer snk_live_xxxx" \
      "https://api.sentinelnerd.com/v1/events?source=unifi_network&severity=high&from=2025-01-15T00:00:00Z&per_page=10"
Example Response 
{
  "data": [
    {
      "id": "evt_abc123",
      "type": "ids_alert",
      "source": "unifi_network",
      "severity": "high",
      "timestamp": "2025-01-15T14:32:01Z",
      "raw": {
        "signature_id": 2024897,
        "signature": "ET SCAN Potential SSH Scan",
        "src_ip": "203.0.113.42",
        "dst_ip": "192.168.1.100",
        "dst_port": 22
      },
      "enrichment": {
        "geo": { "country": "CN", "city": "Beijing" },
        "abuse_ipdb": { "score": 87 }
      }
    }
  ],
  "pagination": {
    "total": 342,
    "page": 1,
    "per_page": 10,
    "total_pages": 35
  }
}

Get Single Event

GET /v1/events/:id

Retrieve a single event by ID with full details and enrichment data.

Example Request 

curl -H "Authorization: Bearer snk_live_xxxx" \
      https://api.sentinelnerd.com/v1/events/evt_abc123

Search Events

POST /v1/events/search

Advanced event search with complex filters and aggregations.

Parameter Type Required Description
query object Required Search query with field-level filters
aggs object Optional Aggregation definitions (count, terms, histogram)
sort object Optional Sort order for results
limit integer Optional Max results to return (default: 50)
Search Request 
curl -X POST https://api.sentinelnerd.com/v1/events/search \
  -H "Authorization: Bearer snk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "bool": {
        "must": [
          { "field": "source", "equals": "unifi_network" },
          { "field": "raw.dst_port", "in": [22, 23, 3389] }
        ],
        "must_not": [
          { "field": "raw.src_ip", "prefix": "192.168." }
        ]
      },
      "time_range": {
        "from": "2025-01-14T00:00:00Z",
        "to": "2025-01-15T23:59:59Z"
      }
    },
    "aggs": {
      "by_source_ip": {
        "terms": { "field": "raw.src_ip", "size": 10 }
      }
    },
    "sort": { "timestamp": "desc" },
    "limit": 20
  }'

Submit Custom Event

POST /v1/events

Submit a custom event for processing by the detection engine.

Parameter Type Required Description
type string Required Event type identifier
source string Required Event source (use "custom" for custom events)
severity string Optional Event severity (default: info)
data object Required Event payload (arbitrary JSON)
Submit Custom Event 
curl -X POST https://api.sentinelnerd.com/v1/events \
  -H "Authorization: Bearer snk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "vpn_login",
    "source": "custom",
    "severity": "info",
    "data": {
      "user": "jsmith",
      "src_ip": "203.0.113.42",
      "vpn_type": "wireguard"
    }
  }'

Export Events

POST /v1/events/export

Export events as CSV or JSON for the specified time range. Returns a download URL.

Note

Event exports are processed asynchronously. The response includes a download_url that becomes available once the export is complete (usually within a few seconds for small exports).