API Usage Guide

On This Page

Authentication

QuickSearch uses JWT tokens and API keys for authentication.

Generate API Key
Terminal
# Login to get JWT token
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "admin123"}'

# Response contains JWT token
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": { "id": 1, "email": "[email protected]" }
}

# Create API key via web interface or API
curl -X POST http://localhost:3000/api/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production API"}'
Use API keys for programmatic access. Include them in the Authorization header as Bearer YOUR_API_KEY.

Event Ingestion API

Ingest structured application events via the REST API.

POST /api/events

Submit application events to QuickSearch

Basic Event
Terminal
curl -X POST http://localhost:3000/api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "type": "user_login",
    "application": "web_app",
    "message": "User logged in successfully",
    "data": {
      "user_id": "12345",
      "username": "johndoe",
      "ip_address": "192.168.1.100"
    }
  }'
Event with Severity
Terminal
curl -X POST http://localhost:3000/api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "type": "payment_processed",
    "application": "billing",
    "severity": "information",
    "message": "Payment processed successfully",
    "data": {
      "order_id": "ORD-12345",
      "amount": 99.99,
      "currency": "USD",
      "payment_method": "stripe"
    }
  }'
Error Event
Terminal
curl -X POST http://localhost:3000/api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "type": "database_error",
    "application": "api",
    "severity": "error",
    "message": "Failed to connect to database",
    "hostname": "api-server-01",
    "data": {
      "error_code": "CONN_TIMEOUT",
      "database": "postgres_main",
      "retry_attempt": 3
    }
  }'
Request Schema
Field Type Required Description
type string Yes Event type identifier
application string Yes Application name
message string No Human-readable message
severity string No Log level (debug, info, warning, error)
hostname string No Source hostname
data object No Additional event data

Syslog API

Accept syslog messages from Linux servers and network devices.

POST /api/syslog

Submit syslog messages in JSON or RFC3164 format

Structured Syslog
Terminal
curl -X POST http://localhost:3000/api/syslog \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "type": "auth_failure",
    "severity": "error",
    "hostname": "web-server-01",
    "message": "Authentication failed for user admin",
    "data": {
      "user": "admin",
      "source_ip": "10.0.0.50",
      "service": "ssh"
    }
  }'
Raw Syslog String (RFC3164)
Terminal
curl -X POST http://localhost:3000/api/syslog \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '"<34>Oct 11 22:14:15 mymachine su: '\''su root'\'' failed for user'"'
Raw syslog strings must be sent as a JSON string (double quotes around the syslog message).

Search API

Retrieve and search events with powerful filtering options.

GET /api/events

Search and retrieve events

Get Recent Events
Terminal
# Get recent 100 events
curl "http://localhost:3000/api/events?limit=100"

# Get recent 50 events with offset
curl "http://localhost:3000/api/events?limit=50&offset=0"
Search with Query
Terminal
# Search for specific text
curl "http://localhost:3000/api/events?q=login"

# Search with filters
curl "http://localhost:3000/api/events?q=error&source=api&limit=20"
Filter by Source
Terminal
# API events only
curl "http://localhost:3000/api/events?source=api"

# Syslog events only
curl "http://localhost:3000/api/events?source=syslog"
Filter by Application
Terminal
# Events from specific application
curl "http://localhost:3000/api/events?application=web_app"
Filter by Event Type
Terminal
# Specific event type
curl "http://localhost:3000/api/events?type=user_login"
Time Range Filters
Terminal
# Events after timestamp (ISO format)
curl "http://localhost:3000/api/events?timestamp_gte=2024-01-01T00:00:00Z"

# Events before timestamp
curl "http://localhost:3000/api/events?timestamp_lte=2024-12-31T23:59:59Z"

# Events within time range
curl "http://localhost:3000/api/events?timestamp_gte=2024-01-01T00:00:00Z&timestamp_lte=2024-12-31T23:59:59Z"
Query Parameters
Parameter Type Description
q string Search query text
limit integer Max results (default: 20)
offset integer Pagination offset
source string Filter by source (api/syslog)
application string Filter by application name
type string Filter by event type
timestamp_gte ISO datetime Events after timestamp
timestamp_lte ISO datetime Events before timestamp

Event Data Structure

All log entries are stored with flattened fields for optimal searchability.

Stored Event Schema
{
  // Core fields
  "document_type": "log_entry",
  "timestamp": "2024-12-30T10:30:00.000Z",
  "timestamp_iso": "2024-12-30T10:30:00.000Z",
  "timestamp_unix": 1735547400,
  "type": "user_login",
  "source": "api",
  "application": "web_app",
  "message": "User logged in successfully",
  "hostname": "web-server-01",
  "severity": "information",

  // Flattened data fields (all fields from data object)
  "user_id": "12345",
  "username": "johndoe",
  "ip_address": "192.168.1.100",
  "browser": "Chrome"
}
Key Feature: All nested fields in the data object are flattened to top-level. This means data.user_id becomes user_id, making all data directly searchable.

Web Interface

The web interface provides a visual way to explore and search logs.

Event Feed

View real-time stream of incoming events with auto-refresh.

Search & Filter

Full-text search with filters for source, application, and type.

Event Details

Click any event to view complete details with all fields.

Access Points
Web Interface:
http://localhost:3000
API Base:
http://localhost:3000/api
Next Steps