API Reference

Complete API documentation for the Spark Strand notifications service. The API supports independent applications where each app manages its own provider credentials and gets isolated endpoints.

Base URL

https://notifications.sparkstrand.com/api

How It Works

App Registration

Each application registers with the notification service using its own provider API keys. The system creates isolated provider instances and automatically routes notifications through the best available provider for each channel.

// App registration flow
POST /api/applications/register
ā†’ Creates isolated provider instances
ā†’ Routes notifications per app
ā†’ Provides app-specific endpoints

Provider Isolation

Each registered app gets its own isolated provider instances:

  • ā€¢ sporty-expats-novu: Novu provider with SportyExpats' API keys
  • ā€¢ sporty-expats-resend: Resend provider with SportyExpats' API keys
  • ā€¢ tax-done-novu: Novu provider with TaxDone's API keys
  • ā€¢ venture-direction-twilio: Twilio provider with VentureDirection's credentials

Authentication

API Key

All API requests require an API key to be included in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Rate Limiting

API requests are rate limited per application to prevent abuse.

  • ā€¢ Standard: 100 requests per minute per app
  • ā€¢ Bulk operations: 10 requests per minute per app
  • ā€¢ Health checks: 1000 requests per minute per app
  • ā€¢ App registration: 5 registrations per hour

API Endpoints

Health Check

GET /health

Check service health, system resources, and provider status

App Registration

POST /applications/register

Register a new application with provider credentials

App Status

GET /applications/{appId}/status

Get application status and provider health

Send Notification

POST /notifications

Send a notification via the unified service

Get Notification

GET /notifications/{id}

Get notification status and delivery details

List Notifications

GET /notifications

List notifications with pagination and filtering

Provider Status

GET /providers/status

Get status of all registered providers

Metrics

GET /metrics

Get system metrics and delivery statistics

Request/Response Examples

App Registration

POST /api/applications/register
{
"appId": "sporty-expats",
"name": "SportyExpats",
"description": "Sports community platform",
"providers": {
"novu": {
"apiKey": "novu-api-key",
"appId": "novu-app-id",
"priority": 1
},
"resend": {
"apiKey": "resend-api-key",
"fromEmail": "notifications@sportyexpats.com",
"priority": 2
}
}
}

Send Notification

POST /api/notifications
{
"appId": "sporty-expats",
"userId": "user-123",
"type": "WELCOME",
"title": "Welcome to SportyExpats!",
"content": "We're excited to have you on board.",
"channels": { "email": true, "inApp": true },
"metadata": {
"email": "user@example.com",
"firstName": "John"
}
}

Error Handling

Common Error Codes

VALIDATION_ERRORRequest validation failed
AUTHENTICATION_ERRORInvalid or missing API key
RATE_LIMIT_EXCEEDEDRate limit exceeded for this app
APP_NOT_REGISTEREDApplication not registered with the service
PROVIDER_UNAVAILABLERequested provider is not available
CHANNEL_NOT_SUPPORTEDDelivery channel not supported by app's providers

Monitoring & Analytics

Provider Status

Monitor the health and availability of all registered providers:

  • ā€¢ Provider health status
  • ā€¢ Rate limit usage
  • ā€¢ Error rates and types
  • ā€¢ Response times

Delivery Metrics

Track notification delivery performance:

  • ā€¢ Delivery success rates
  • ā€¢ Channel performance
  • ā€¢ App-specific statistics
  • ā€¢ Fallback usage