Events API | SentinelNerd

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).