API Reference

Complete API documentation for LogWard. Base URL: http://localhost:8080/api/v1

Authentication

LogWard uses two authentication methods:

1. Session-based Authentication (Bearer Token) Dashboard

For dashboard and user-facing endpoints (organizations, projects, alerts).

bash 
# Login to get token
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'

# Use token in requests
curl http://localhost:8080/api/v1/organizations \
  -H "Authorization: Bearer your_token_here"

2. API Key Authentication Logs

For log ingestion and query endpoints. API keys are project-scoped and prefixed with lp_.

bash 
curl -X POST http://localhost:8080/api/v1/ingest \
  -H "X-API-Key: lp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"logs": [...]}'

Log Ingestion

POST /api/v1/ingest

Ingest logs in batch (max 1000 logs per request).

Request Body

json 
{
  "logs": [
    {
      "time": "2025-01-15T10:30:00Z",
      "service": "api-gateway",
      "level": "error",
      "message": "Database connection timeout",
      "metadata": {
        "user_id": 123,
        "endpoint": "/api/users",
        "duration_ms": 5000
      },
      "trace_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

Schema

  • time (string, required) - ISO 8601 timestamp
  • service (string, required) - Service name (max 100 chars)
  • level (string, required) - Log level: debug, info, warn, error, critical
  • message (string, required) - Log message
  • metadata (object, optional) - Additional structured data (JSON)
  • trace_id (string, optional) - Distributed tracing ID (UUID format)

Response (200 OK)

json 
{
  "received": 1,
  "timestamp": "2025-01-15T10:30:02Z"
}

Log Query

GET /api/v1/logs

Search and filter logs with various parameters.

Query Parameters

  • service (optional) - Filter by service name
  • level (optional) - Filter by level (debug, info, warn, error, critical)
  • from (optional) - Start time (ISO 8601)
  • to (optional) - End time (ISO 8601)
  • q (optional) - Full-text search on message
  • limit (optional) - Results per page (default: 100, max: 1000)
  • offset (optional) - Pagination offset (default: 0)

Examples

bash 
# Get all error logs
curl "http://localhost:8080/api/v1/logs?level=error&limit=50" \
  -H "X-API-Key: lp_your_api_key_here"

# Filter by service and time range
curl "http://localhost:8080/api/v1/logs?service=api-gateway&from=2025-01-15T00:00:00Z&to=2025-01-15T23:59:59Z" \
  -H "X-API-Key: lp_your_api_key_here"

# Full-text search
curl "http://localhost:8080/api/v1/logs?q=timeout&limit=20" \
  -H "X-API-Key: lp_your_api_key_here"

Live Streaming

GET /api/v1/logs/stream

Live tail logs via Server-Sent Events (SSE).

cURL Example

bash 
curl -N "http://localhost:8080/api/v1/logs/stream?service=api-gateway" \
  -H "X-API-Key: lp_your_api_key_here"

JavaScript Example

javascript 
const eventSource = new EventSource(
  'http://localhost:8080/api/v1/logs/stream?service=api-gateway',
  {
    headers: {
      'X-API-Key': 'lp_your_api_key_here'
    }
  }
);

eventSource.addEventListener('log', (event) => {
  const log = JSON.parse(event.data);
  console.log('New log:', log);
});

eventSource.onerror = (error) => {
  console.error('SSE error:', error);
};

Alerts

GET /api/v1/projects/:projectId/alerts

List all alert rules for a project.

Example

bash 
curl http://localhost:8080/api/v1/projects/project-uuid/alerts \
  -H "Authorization: Bearer your_token_here"

POST /api/v1/projects/:projectId/alerts

Create a new alert rule.

Example

bash 
curl -X POST http://localhost:8080/api/v1/projects/project-uuid/alerts \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Error Rate Alert",
    "condition": {
      "field": "level",
      "operator": "equals",
      "value": "error",
      "threshold": 100,
      "timeWindow": "5m"
    },
    "notifications": [
      {
        "type": "email",
        "config": {
          "recipients": ["ops@example.com"]
        }
      }
    ],
    "enabled": true
  }'

Error Handling

All errors follow this format:

json 
{
  "error": "Error message description",
  "code": "ERROR_CODE",
  "statusCode": 400
}

Common HTTP Status Codes

  • 200 OK - Success
  • 201 Created - Resource created
  • 400 Bad Request - Invalid input
  • 401 Unauthorized - Missing or invalid authentication
  • 403 Forbidden - Not authorized
  • 404 Not Found - Resource not found
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error