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

Public Topics

Authentication required to publish, anyone can subscribe:

# Requires API key or JWT to publish
curl -d "Public announcement" \
  -H "X-API-Key: noti_your_key_here" \
  https://app.notifer.io/announcements

• Discoverable in the public topic browser
• Authentication required to publish (prevents spam)
• Anyone can subscribe and read without authentication
• Great for community notifications with trusted publishers

Private Topics

Private topics require authentication for both publishing and subscribing:

# Requires topic token, API key, or JWT
curl -d "Confidential data" \
  -H "X-Topic-Token: tk_your_token_here" \
  https://app.notifer.io/private-alerts

• Full access control via topic tokens
• Subscription requires owner approval (by default)
• Optionally discoverable - allows read-only public subscriptions
• Available on ESSENTIALS plan and higher

Private Discoverable Topics

Private topics can be made discoverable in the public catalog, enabling read-only subscriptions:

# Only owner/token holders can publish
curl -d "Company announcement" \
  -H "X-Topic-Token: tk_your_token_here" \
  https://app.notifer.io/announcements

• Anyone can find and subscribe via the catalog
• Subscribers receive notifications (read-only)
• Only owner and token holders can publish
• Perfect for announcements and status updates

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	1 (critical)
X-Tags	Comma-separated tags	[]	"server,critical"

Priority Levels

Priority	Name	Use Case	Color
1	Critical	System down, major outage	Red
2	High	Urgent, requires attention	Orange
3	Default	Standard notifications	Blue
4	Low	Informational, can wait	Gray
5	Info	Debug messages, verbose logging	Cyan

For detailed priority level documentation, see Priority Levels.

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

For detailed tags documentation, see Message Tags.

Receiving Messages

Web & Mobile App (Account Required)

To view and receive messages in the Notifer app:

1. Create an account at app.notifer.io
2. Log in to the web or mobile app
3. Browse or search for topics
4. Subscribe to topics you want to follow

Push notifications let you receive alerts even when the app is closed:

• Enable browser notifications (web)
• Install the mobile app for iOS/Android push notifications

Programmatic Access (No Account for Public Topics)

Developers can access public topics without authentication:

SSE (Server-Sent Events) - Real-time streaming for applications:

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

CLI - Command-line streaming:

notifer subscribe my-topic

API - Fetch message history:

curl https://app.notifer.io/my-topic/json

note

For private topics, you must provide an API key, topic token, or JWT token.

Notification Settings

Control which messages trigger push 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)

Authentication

What Requires an Account?

Action	Public Topics	Private Topics
Create topics	Account required	Account required
View in web/mobile app	Account required	Account required
Subscribe (push notifications)	Account required	Account required + permission
Publish messages	Authentication required (JWT/API Key)	Authentication required (token/JWT/API Key)
SSE/API access (read)	No account needed	Authentication required

Authentication Methods

API Keys - For scripts and integrations:

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

Topic Access Tokens - For private topic access (share with external systems):

curl -H "X-Topic-Token: tk_your_token_here" \
  -d "Message" \
  https://app.notifer.io/my-private-topic

JWT Tokens - For web/mobile apps after login:

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

Message Retention

• Messages are stored for up to 60 days (depending on your plan)
• Last 100 messages per topic are cached for instant retrieval
• Older messages are available via API pagination

Limits

Limits vary by subscription tier.

See Pricing for details.

Next Steps

• Web App Guide - Use the dashboard
• Publishing Methods - Different ways to publish
• Private Topics - Secure your notifications