API Overview

The Sentinel Nerd REST API lets you programmatically access events, manage detection rules, and configure alerts. All API endpoints return JSON.

Base URL

All API requests are made to:

https://api.sentinelnerd.com/v1

Authentication

All requests require a Bearer token in the Authorization header. See the Authentication page for details on generating and managing API keys.

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

Request Format

For POST, PUT, and PATCH requests, send a JSON body with the Content-Type: application/json header.

Response Format

All responses return JSON with a consistent envelope:

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T14:32:01Z"
  }
}

{
  "data": [ ... ],
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T14:32:01Z"
  },
  "pagination": {
    "total": 1250,
    "page": 1,
    "per_page": 50,
    "total_pages": 25
  }
}

Error Handling

Errors return an appropriate HTTP status code with a JSON error body:

{
  "error": {
    "code": "validation_error",
    "message": "The 'severity' field must be one of: critical, high, medium, low, info",
    "details": [
      {
        "field": "severity",
        "message": "Invalid value: 'urgent'"
      }
    ]
  },
  "meta": {
    "request_id": "req_def456"
  }
}

HTTP Status Codes

Pagination

List endpoints support cursor-based and page-based pagination:

# Page-based
    GET /v1/events?page=2&per_page=50

    # Cursor-based (recommended for large datasets)
    GET /v1/events?after=evt_abc123&limit=50

Rate Limiting

API requests are rate-limited per API key:

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
    X-RateLimit-Remaining: 287
    X-RateLimit-Reset: 1705329600

API Endpoints

• Authentication — API keys, scopes, and token management
• Events — Query, search, and export security events (with class filter for security / network / audit)
• Flows — NetFlow / IPFIX traffic data: paginated flows, top talkers, protocol breakdown
• Rules — Create, update, and manage detection rules
• Alerts — List, acknowledge, and resolve alerts