API Reference¶

Complete reference for all Notifer API endpoints.

Interactive Documentation

For the most up-to-date and interactive API documentation, visit:

Swagger UI: https://app.notifer.io/docs
ReDoc: https://app.notifer.io/redoc

Base URL¶

https://app.notifer.io

Publishing Messages¶

Publish Message¶

Publish a message to a topic.

POST /{topic}
PUT /{topic}

Headers:

Content-Type: text/plain
X-Title: Message title (optional)
X-Priority: 1-5 (optional, default: 3)
X-Tags: tag1,tag2,tag3 (optional)
X-Markdown: true|false (optional, default: false)
Authorization: Bearer <token> (optional, for private topics)
X-API-Key: <api_key> (optional, alternative auth)

Request Body:

Plain text message content

Example:

curl -X POST https://app.notifer.io/server-alerts \
  -H "X-Title: Server Down" \
  -H "X-Priority: 5" \
  -H "X-Tags: critical,server,production" \
  -d "Production server prod-web-01 is not responding"

Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "topic": "server-alerts",
  "message": "Production server prod-web-01 is not responding",
  "title": "Server Down",
  "priority": 5,
  "tags": ["critical", "server", "production"],
  "timestamp": "2025-01-15T10:30:00Z"
}

Topics¶

List Topics¶

Get all topics for the authenticated user.

GET /api/topics

Headers:

Authorization: Bearer <token>

Query Parameters: - page (int, optional): Page number (default: 1) - per_page (int, optional): Items per page (default: 20, max: 100)

Response: 200 OK

[
  {
    "id": "uuid",
    "name": "server-alerts",
    "owner_id": "uuid",
    "access_level": "private",
    "description": "Production server monitoring",
    "is_discoverable": false,
    "message_count": 42,
    "subscriber_count": 5,
    "created_at": "2025-01-01T00:00:00Z",
    "last_message_at": "2025-01-15T10:30:00Z"
  }
]

Create Topic¶

Create a new topic.

POST /api/topics

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "name": "my-topic",
  "access_level": "public|private|protected",
  "description": "Topic description (optional)",
  "is_discoverable": true,
  "icon_name": "bell",
  "icon_color": "blue"
}

Response: 201 Created

Get Topic¶

Get topic details.

GET /api/topics/{topic}

Response: 200 OK

Update Topic¶

Update topic settings.

PATCH /api/topics/{topic}

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "description": "Updated description",
  "is_discoverable": false,
  "icon_name": "server",
  "icon_color": "red"
}

Response: 200 OK

Delete Topic¶

Delete a topic permanently.

DELETE /api/topics/{topic}

Headers:

Authorization: Bearer <token>

Response: 204 No Content

Messages¶

Get Message History¶

Get message history for a topic (JSON format).

GET /{topic}/json

Query Parameters: - limit (int, optional): Max messages to return (default: 100, max: 500) - since (ISO datetime, optional): Get messages since this timestamp

Example:

curl "https://app.notifer.io/server-alerts/json?limit=50"

Response: 200 OK

[
  {
    "id": "uuid",
    "topic_id": "uuid",
    "topic_name": "server-alerts",
    "message": "Server is down",
    "title": "Alert",
    "priority": 5,
    "tags": ["critical"],
    "timestamp": "2025-01-15T10:30:00Z"
  }
]

Search Messages¶

Search across all user's topics.

GET /api/messages

Headers:

Authorization: Bearer <token>

Query Parameters: - q (string): Search query - topic (string, optional): Filter by topic name - tags (string, optional): Filter by tags (comma-separated) - priority_min (int, optional): Minimum priority (1-5) - priority_max (int, optional): Maximum priority (1-5) - page (int, optional): Page number - per_page (int, optional): Items per page

Example:

curl "https://app.notifer.io/api/messages?q=server&tags=critical&priority_min=4" \
  -H "Authorization: Bearer $TOKEN"

Response: 200 OK

Subscriptions¶

Subscribe to topic via Server-Sent Events (long-running connection).

GET /{topic}/sse

Query Parameters: - token (string, optional): JWT token for private topics - since_id (uuid, optional): Get messages since this message ID

Example:

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

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

Response: SSE stream

event: message
data: {"id":"uuid","topic":"server-alerts","message":"Hello",...}

event: message
data: {"id":"uuid","topic":"server-alerts","message":"World",...}

Subscribe to topic via WebSocket.

WS /{topic}/ws

Query Parameters: - token (string, optional): JWT token for private topics

Example:

const ws = new WebSocket('wss://app.notifer.io/my-topic/ws?token=<TOKEN>');

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log(message);
};

Authentication¶

Register¶

Register a new user account.

POST /auth/register

Request Body:

{
  "email": "user@example.com",
  "username": "username",
  "password": "strong-password"
}

Response: 201 Created

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 86400
}

Login with email and password.

POST /auth/login

Request Body:

{
  "email": "user@example.com",
  "password": "password"
}

Response: 200 OK

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 86400
}

Google OAuth¶

Login or register with Google.

GET /auth/google

Redirects to Google OAuth flow.

Get Current User¶

Get authenticated user's profile.

GET /auth/me

Headers:

Authorization: Bearer <token>

Response: 200 OK

{
  "id": "uuid",
  "email": "user@example.com",
  "username": "username",
  "avatar_url": null,
  "subscription_tier": "free",
  "created_at": "2025-01-01T00:00:00Z"
}

Refresh Token¶

Refresh access token using refresh token.

POST /auth/refresh

Request Body:

{
  "refresh_token": "eyJ..."
}

Response: 200 OK

API Keys¶

List API Keys¶

Get all API keys for the authenticated user.

GET /api/keys

Headers:

Authorization: Bearer <token>

Response: 200 OK

[
  {
    "id": "uuid",
    "name": "Production Server",
    "key_prefix": "noti_abc",
    "created_at": "2025-01-01T00:00:00Z",
    "expires_at": null,
    "last_used_at": "2025-01-15T10:00:00Z"
  }
]

Create API Key¶

Create a new API key.

POST /api/keys

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "name": "CI/CD Pipeline",
  "expires_at": "2026-01-01T00:00:00Z"
}

Response: 201 Created

{
  "id": "uuid",
  "key": "noti_abc123...",
  "name": "CI/CD Pipeline",
  "created_at": "2025-01-15T10:30:00Z",
  "expires_at": "2026-01-01T00:00:00Z"
}

Save the Key

The full key is only shown once. Save it securely!

Revoke API Key¶

Revoke an API key.

DELETE /api/keys/{key_id}

Headers:

Authorization: Bearer <token>

Response: 204 No Content

Topic Access Tokens¶

List Topic Tokens¶

Get all access tokens for a topic.

GET /api/topics/{topic}/access-tokens

Headers:

Authorization: Bearer <token>

Response: 200 OK

Create Topic Token¶

Create a new topic access token.

POST /api/topics/{topic}/access-tokens

Request Body:

{
  "name": "External Service",
  "permissions": ["read", "write"],
  "expires_at": "2026-01-01T00:00:00Z"
}

Response: 201 Created

Revoke Topic Token¶

Revoke a topic access token.

DELETE /api/topics/{topic}/access-tokens/{token_id}

Response: 204 No Content

Teams¶

List Teams¶

Get all teams for the authenticated user.

GET /api/teams

Headers:

Authorization: Bearer <token>

Response: 200 OK

Create Team¶

Create a new team.

POST /api/teams

Request Body:

{
  "name": "Engineering Team",
  "description": "DevOps and Backend"
}

Response: 201 Created

Invite Team Member¶

Invite a user to the team.

POST /api/teams/{team_id}/members

Request Body:

{
  "email": "member@example.com",
  "role": "member|admin"
}

Response: 201 Created

Subscriptions (Mobile/Push)¶

Register Device¶

Register a mobile device for push notifications.

POST /api/devices

Request Body:

{
  "pushToken": "ExponentPushToken[xxx]",
  "platform": "ios|android",
  "deviceId": "unique-device-id",
  "deviceName": "iPhone 13 Pro"
}

Response: 201 Created

Create Subscription¶

Subscribe a device to a topic.

POST /api/subscriptions

Request Body:

{
  "device_id": "uuid",
  "topic_name": "server-alerts",
  "notification_settings": {
    "sound_enabled": true,
    "vibrate_enabled": true,
    "priority_threshold": 3,
    "tags_filter": []
  }
}

Response: 201 Created

Error Responses¶

All error responses follow this format:

{
  "detail": "Error message"
}

Common Status Codes¶

Code	Meaning
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
422	Validation Error
429	Rate Limit Exceeded
500	Internal Server Error

Rate Limiting¶

See API Overview - Rate Limiting for details.

Next Steps¶

Authentication Guide - Learn about auth methods
API Overview - Understanding the API structure
Publishing Guide - Publish messages
SSE Guide - Real-time subscriptions

Interactive Documentation¶

For the most comprehensive and up-to-date API documentation, use the interactive Swagger UI:

https://app.notifer.io/docs

The interactive docs allow you to: - Try API calls directly from your browser - See all request/response schemas - View detailed parameter descriptions - Test authentication flows

API Reference¶

Base URL¶

Publishing Messages¶

Publish Message¶

Topics¶

List Topics¶

Create Topic¶

Get Topic¶

Update Topic¶

Delete Topic¶

Messages¶

Get Message History¶

Search Messages¶

Subscriptions¶

Subscribe via SSE¶

Subscribe via WebSocket¶

Authentication¶

Register¶

Login¶

Google OAuth¶

Get Current User¶

Refresh Token¶

API Keys¶

List API Keys¶

Create API Key¶

Revoke API Key¶

Topic Access Tokens¶

List Topic Tokens¶

Create Topic Token¶

Revoke Topic Token¶

Teams¶

List Teams¶

Create Team¶

Invite Team Member¶

Subscriptions (Mobile/Push)¶

Register Device¶

Create Subscription¶

Error Responses¶

Common Status Codes¶

Rate Limiting¶

Next Steps¶

Interactive Documentation¶