Skip to main content

API Overview

Notifer provides a simple REST API for programmatic access to topics, messages, and subscriptions.

Base URL​

https://app.notifer.io

All API endpoints are served from the same domain as the web application.

API Structure​

The Notifer API follows REST principles and uses:

  • HTTP methods: GET, POST, PUT, PATCH, DELETE
  • JSON for request/response bodies (except simple publishing)
  • Standard HTTP status codes
  • JWT tokens for authentication

Endpoints Overview​

Publishing Messages​

MethodEndpointDescription
POST/{topic}Publish message to topic
PUT/{topic}Publish message to topic (alias)

Topics Management​

MethodEndpointDescription
GET/api/topicsList all topics
GET/api/topics/myList user's owned topics (requires auth)
GET/api/topics/publicList public/discoverable topics
POST/api/topicsCreate new topic (requires auth)
GET/api/topics/{name}Get topic details by name
GET/api/topics/{name}/statsGet topic statistics
GET/api/topics/{name}/messagesSearch topic messages
PATCH/api/topics/{topic_id}Update topic settings (by UUID)
DELETE/api/topics/{topic_id}Delete topic (by UUID)

Messages​

MethodEndpointDescription
GET/{topic}/jsonGet message history (JSON)
GET/api/messages/searchSearch messages with filters
GET/api/messages/recentGet recent messages from subscribed topics
GET/api/messages/activityGet message activity stats for charts
DELETE/api/{topic}/messages/{id}Soft-delete message (ESSENTIALS+)
PATCH/api/{topic}/messages/{id}Edit message (ESSENTIALS+)

Real-time Subscriptions​

MethodEndpointDescription
GET/sseSubscribe to multiple topics (multi-SSE)
POST/api/sse/sessionsCreate SSE session for short URLs
GET/{topic}/sseSubscribe to single topic via SSE
WS/{topic}/wsSubscribe via WebSocket

Authentication​

MethodEndpointDescription
POST/auth/registerRegister new user
POST/auth/loginLogin (email/password)
GET/auth/google/loginInitiate Google OAuth
POST/auth/apple/mobileApple Sign-In (iOS)
GET/auth/meGet current user
POST/auth/refreshRefresh access token
GET/auth/verify-emailVerify email address
POST/auth/resend-verificationResend verification email
POST/auth/password-reset/requestRequest password reset
POST/auth/password-reset/confirmConfirm password reset
POST/auth/password-changeChange password
POST/auth/accept-termsAccept Terms of Service
GET/auth/consent-historyGet consent history (GDPR)

User Management​

MethodEndpointDescription
GET/api/users/meGet current user profile
PATCH/api/users/meUpdate user profile
GET/api/users/me/dataExport user data (GDPR)
DELETE/api/users/meDelete account (GDPR)

Devices (Mobile)​

MethodEndpointDescription
POST/api/devices/registerRegister device for push
GET/api/devices/myList user's devices
GET/api/devices/{id}Get device details
PUT/api/devices/{id}Update device
DELETE/api/devices/{id}Delete device
POST/api/devices/{id}/testSend test notification

Subscriptions​

MethodEndpointDescription
GET/api/subscriptionsList user's subscriptions
POST/api/subscriptionsCreate subscription
PATCH/api/subscriptions/{id}Update subscription settings
DELETE/api/subscriptions/{id}Delete subscription
DELETE/api/subscriptions/by-topic/{name}Unsubscribe by topic name
GET/api/subscriptions/check/{name}Check if subscribed

API Keys​

MethodEndpointDescription
GET/api/keysList API keys
POST/api/keysCreate API key
DELETE/api/keys/{key_id}Revoke API key

Topic Access Tokens​

MethodEndpointDescription
GET/api/topics/{topic}/access-tokensList tokens
POST/api/topics/{topic}/access-tokensCreate token
DELETE/api/topics/{topic}/access-tokens/{token_id}Revoke token

Teams (TEAM+ Plan)​

MethodEndpointDescription
GET/api/teamsList user's teams
GET/api/teams/statsGet team statistics
GET/api/teams/deactivatedList deactivated teams
POST/api/teamsCreate team
GET/api/teams/{team_id}Get team details
PATCH/api/teams/{team_id}Update team
DELETE/api/teams/{team_id}Delete team
POST/api/teams/{team_id}/reactivateReactivate team
GET/api/teams/{team_id}/membersList team members
PATCH/api/teams/{team_id}/members/{user_id}Update member role
DELETE/api/teams/{team_id}/members/{user_id}Remove member
POST/api/teams/{team_id}/invitesInvite member
GET/api/teams/{team_id}/invitesList pending invites
POST/api/teams/invites/acceptAccept invite
POST/api/teams/invites/{id}/resendResend invite
DELETE/api/teams/invites/{id}Cancel invite

Response Format​

Success Response​

{
  "id": "uuid",
  "name": "my-topic",
  "created_at": "2025-01-15T10:30:00Z",
  "message_count": 42
}

Error Response​

{
  "detail": "Topic not found"
}

HTTP Status Codes​

CodeMeaning
200Success
201Created
204No Content (successful deletion)
400Bad Request (invalid input)
401Unauthorized (authentication required)
403Forbidden (insufficient permissions)
404Not Found
409Conflict (e.g., topic name already exists)
422Unprocessable Entity (validation error)
429Rate Limit Exceeded
500Internal Server Error

Rate Limiting​

Rate limits vary by subscription tier:

Plan limits:

When rate limited, the API returns HTTP 429 with header:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1641024000

Pagination​

List endpoints support pagination:

GET /api/topics?page=1&per_page=20

Parameters:

  • page - Page number (default: 1)
  • per_page - Items per page (default: 20, max: 100)

Response headers:

X-Total-Count: 150
X-Page: 1
X-Per-Page: 20

Interactive Documentation​

Explore the full API interactively using Swagger UI:

https://app.notifer.io/docs

Or ReDoc format:

https://app.notifer.io/redoc

SDKs and Libraries​

Official SDKs​

Community Libraries​

Check GitHub for community-contributed libraries.

Examples​

Publishing with Authentication​

# Get JWT token first
TOKEN=$(curl -X POST https://app.notifer.io/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secret"}' \
  | jq -r '.access_token')

# Publish to private topic
curl -d "Authenticated message" \
  -H "Authorization: Bearer $TOKEN" \
  https://app.notifer.io/my-private-topic

Creating a Topic​

curl -X POST https://app.notifer.io/api/topics \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "server-alerts",
    "access_level": "private",
    "description": "Production server monitoring",
    "is_discoverable": false
  }'

Subscribing via SSE​

# Public topic
curl -N https://app.notifer.io/server-alerts/sse

# Private topic
curl -N "https://app.notifer.io/server-alerts/sse?token=$TOKEN"

Next Steps​

Support​