Skip to content

Core Concepts

Understanding the key concepts in Notifer will help you use it effectively.

Topics

Topics are channels for messages. Think of them like chat rooms or RSS feeds.

  • Topic names are part of the URL: https://app.notifer.io/my-topic
  • Topics must be created explicitly before publishing messages
  • Create topics via the web app or API
  • Anyone can subscribe to public topics without authentication
  • Private topics require authentication and owner permission

Topic Naming Rules

  • Use lowercase letters, numbers, hyphens, and underscores
  • Length: 3-64 characters
  • Examples: server-alerts, my_notifications, app123-status

Topic Types

# Anyone can publish and subscribe
curl -d "Public announcement" https://app.notifer.io/announcements
  • Discoverable in the public topic browser
  • No authentication required
  • Great for community notifications

Protected topics require authentication to publish, but anyone can subscribe:

# Requires API key to publish
curl -d "Protected update" \
  -H "X-API-Key: noti_your_key_here" \
  https://app.notifer.io/my-updates
  • Prevents spam and unauthorized publishing
  • Allows public subscriptions

Private topics require authentication for both publishing and subscribing:

# Requires API key or login
curl -d "Confidential data" \
  -H "X-API-Key: noti_your_key_here" \
  https://app.notifer.io/private-alerts
  • Full access control
  • Subscription requires owner approval

Messages

Messages are the notifications sent to topics.

Message Structure

{
  "id": "msg_abc123",
  "topic": "my-topic",
  "title": "Optional Title",
  "message": "Message content",
  "priority": 3,
  "tags": ["tag1", "tag2"],
  "timestamp": "2025-11-02T10:30:00Z"
}

Message Parameters

Parameter Description Default Example
message Message content (required) - "Server is down"
X-Title Message title Topic name "Alert"
X-Priority Priority level 1-5 3 5 (urgent)
X-Tags Comma-separated tags [] "server,critical"

Priority Levels

Priority Description Use Case Icon
1 Min Low importance, FYI
2 Low Minor updates
3 Default Standard notifications
4 High Important alerts
5 Urgent Critical issues

Tags

Tags help categorize and filter messages:

# Multiple tags
curl -d "Database connection lost" \
  -H "X-Tags: database,error,production" \
  https://app.notifer.io/alerts

Tag Features:

  • Filter subscriptions by specific tags
  • Search messages by tags
  • Visual indicators in the UI

Subscriptions

Subscriptions connect you to topics to receive notifications.

Subscription Methods

Real-time updates via Server-Sent Events:

const eventSource = new EventSource('https://app.notifer.io/my-topic/sse');
eventSource.onmessage = (event) => {
  console.log(JSON.parse(event.data));
};

Native push notifications on iOS/Android:

  1. Install the Notifer app
  2. Subscribe to a topic
  3. Receive push notifications even when the app is closed

Command-line streaming:

notifer subscribe my-topic

Subscription Settings

Control which messages trigger notifications:

  • Priority Filter - Only receive messages above a certain priority
  • Tags Filter - Only receive messages with specific tags
  • Sound - Play notification sound
  • Vibration - Vibrate on notification (mobile)

Example mobile subscription:

await api.subscriptions.create({
  topicName: "alerts",
  notificationSettings: {
    priorityThreshold: 4,  // Only priority 4-5
    tagsFilter: ["production", "error"],  // Only these tags
    soundEnabled: true,
    vibrateEnabled: true
  }
});

Authentication

Anonymous Usage

No authentication needed for:

  • Publishing to public topics
  • Subscribing to public topics
  • Reading message history

Authenticated Usage

Create an account for:

  • Creating private topics
  • Managing subscriptions across devices
  • Generating API keys
  • Accessing account settings

Authentication Methods

For web/mobile apps after login:

curl -H "Authorization: Bearer your_jwt_token" \
  https://app.notifer.io/api/topics

For scripts and integrations:

curl -H "X-API-Key: noti_your_key_here" \
  -d "Automated message" \
  https://app.notifer.io/my-topic

Message Retention

  • Messages are stored for 30 days
  • Last 100 messages per topic are cached for instant retrieval
  • Older messages are available via API pagination

Rate Limits

Rate limits vary by subscription tier:

Tier Publish Rate Subscriptions
Free 10/min 5 active
Pro 100/min 50 active
Business 1000/min Unlimited

See Pricing for details.

Next Steps