Skip to 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, DELETE
  • JSON for request/response bodies (except simple publishing)
  • Standard HTTP status codes
  • JWT tokens for authentication

Endpoints Overview

Publishing Messages

Method Endpoint Description
POST /{topic} Publish message to topic
PUT /{topic} Publish message to topic (alias)

Topics Management

Method Endpoint Description
GET /api/topics List all topics (requires auth)
POST /api/topics Create new topic (requires auth)
GET /api/topics/{topic} Get topic details
PATCH /api/topics/{topic} Update topic settings
DELETE /api/topics/{topic} Delete topic

Messages

Method Endpoint Description
GET /{topic}/json Get message history (JSON)
GET /api/messages Search messages (requires auth)

Subscriptions (Real-time)

Method Endpoint Description
GET /{topic}/sse Subscribe via Server-Sent Events
WS /{topic}/ws Subscribe via WebSocket

Authentication

Method Endpoint Description
POST /auth/register Register new user
POST /auth/login Login (email/password)
POST /auth/google Login with Google OAuth
GET /auth/me Get current user
POST /auth/refresh Refresh access token

User Management

Method Endpoint Description
GET /api/users/me Get current user profile
PATCH /api/users/me Update user profile
DELETE /api/users/me Delete account

API Keys

Method Endpoint Description
GET /api/keys List API keys
POST /api/keys Create API key
DELETE /api/keys/{key_id} Revoke API key

Topic Access Tokens

Method Endpoint Description
GET /api/topics/{topic}/access-tokens List tokens
POST /api/topics/{topic}/access-tokens Create token
DELETE /api/topics/{topic}/access-tokens/{token_id} Revoke token

Teams (Pro/Team Plan)

Method Endpoint Description
GET /api/teams List user's teams
POST /api/teams Create 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}/members Invite member

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

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

Rate Limiting

Rate limits vary by subscription tier:

Free Tier

  • Publishing: 100 messages/month total
  • Topics: Max 3 topics
  • API requests: 60 requests/minute per IP

Pro Tier

  • Publishing: 1,000 messages/month
  • Topics: Max 50 topics
  • API requests: 300 requests/minute per IP

Team Tier

  • Publishing: Unlimited
  • Topics: Unlimited
  • API requests: 600 requests/minute per IP

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

  • Interactive Docs: https://app.notifer.io/docs
  • Email: support@notifer.io
  • GitHub Issues: https://github.com/notifer/notifer/issues