Publishing via HTTP¶

The simplest way to publish messages is using HTTP POST or PUT requests.

Basic Publishing¶

POST Request¶

curl -d "Your message here" https://app.notifer.io/your-topic

PUT Request¶

echo "Your message" | curl -T - https://app.notifer.io/your-topic

Both methods work identically - use whichever is more convenient.

Message Parameters¶

Add details to your messages using HTTP headers:

Title¶

curl -d "Deployment completed successfully" \
  -H "X-Title: Production Deploy" \
  https://app.notifer.io/deployments

Priority¶

Set priority from 1 (min) to 5 (urgent):

curl -d "Server is down!" \
  -H "X-Priority: 5" \
  https://app.notifer.io/alerts

Tags¶

Add comma-separated tags:

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

Combined Parameters¶

curl -d "CPU usage at 95%" \
  -H "X-Title: Server Alert" \
  -H "X-Priority: 4" \
  -H "X-Tags: server,cpu,warning" \
  https://app.notifer.io/monitoring

Authentication¶

Public Topics¶

No authentication needed - anyone can publish:

curl -d "Public message" https://app.notifer.io/public-topic

PUBLIC Topic Security

Anyone who knows the topic name can publish to it! This includes:

No authentication required
Only IP-based rate limiting (100 requests/minute per IP)
No way to block specific users

For production systems or sensitive data, use PRIVATE topics instead.

Best practices for PUBLIC topics:

Use hard-to-guess names (e.g., swift-falcon-x8k2jf9a)
Don't share topic names in public repos or documentation
Topics must be created first via dashboard before publishing

Topic must exist before publishing:

# ❌ This will fail if topic doesn't exist (404 error)
curl -d "Message" https://app.notifer.io/nonexistent-topic

# ✅ Create topic first via dashboard, then publish
curl -d "Message" https://app.notifer.io/my-existing-topic

Private Topics¶

Private topics require authentication. You have three options:

Option 1: Topic Access Token (Recommended)¶

Use the X-Topic-Token header with a topic-specific access token:

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

Creating a topic access token:

# First, get a JWT token by logging in
curl -X POST https://app.notifer.io/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"your_password"}'

# Create topic access token
curl -X POST https://app.notifer.io/api/topics/private-topic/access-tokens \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My script token",
    "permissions": ["publish"]
  }'

# Response includes the token:
# {
#   "id": "...",
#   "token": "tk_abc123...",
#   "topic": "private-topic",
#   "permissions": ["publish"]
# }

Alternatively, pass the token as a query parameter:

curl -d "Private message" \
  "https://app.notifer.io/private-topic?token=tk_your_token_here"

Option 2: JWT Token¶

Use the Authorization header with your user JWT token:

curl -d "Private message" \
  -H "Authorization: Bearer eyJhbGciOiJIUz..." \
  https://app.notifer.io/private-topic

Option 3: API Key¶

Use the X-API-Key header with your user API key:

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

Recommendation: Use topic access tokens (Option 1) for automated scripts and integrations, as they: - Are scoped to specific topics - Can have limited permissions (publish-only) - Can be revoked without affecting other integrations

Markdown Formatting¶

Messages support Markdown:

curl -d "**Bold**, *italic*, \`code\`, and [links](https://example.com)" \
  https://app.notifer.io/formatted-messages

Supported Markdown:

**bold** → bold
*italic* → italic
`code` → code
[link](url) → link
# Heading → Heading
- List item → List item
> Quote → Quote
```code block``` → Code block

Response Format¶

Success Response¶

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

Status code: 200 OK or 201 Created

Error Response¶

{
  "detail": "Topic not found or access denied"
}

Common status codes:

400 Bad Request - Invalid parameters
401 Unauthorized - Missing or invalid authentication
403 Forbidden - No permission to publish
404 Not Found - Topic doesn't exist (for private topics)
429 Too Many Requests - Rate limit exceeded

Real-World Examples¶

Server Monitoring¶

#!/bin/bash
# Check disk space and alert if > 80%
USAGE=$(df -h / | awk 'NR==2 {print $5}' | sed 's/%//')
if [ $USAGE -gt 80 ]; then
  curl -d "Disk usage at ${USAGE}%" \
    -H "X-Priority: 4" \
    -H "X-Tags: server,disk,warning" \
    https://app.notifer.io/server-alerts
fi

CI/CD Pipeline¶

# GitHub Actions example
- name: Notify deployment
  run: |
    curl -d "Deployment to production completed" \
      -H "X-Title: Deploy Success" \
      -H "X-Tags: ci,deploy,production" \
      -H "X-Topic-Token: ${{ secrets.NOTIFER_TOPIC_TOKEN }}" \
      https://app.notifer.io/ci-notifications

Database Backup¶

#!/bin/bash
# Backup database and notify
if pg_dump mydb > backup.sql; then
  curl -d "Database backup completed successfully" \
    -H "X-Title: Backup Success" \
    -H "X-Priority: 3" \
    -H "X-Tags: backup,database,success" \
    https://app.notifer.io/backups
else
  curl -d "Database backup FAILED!" \
    -H "X-Title: Backup Failed" \
    -H "X-Priority: 5" \
    -H "X-Tags: backup,database,error" \
    https://app.notifer.io/backups
fi

Log Monitoring¶

# Alert on error in logs
tail -f /var/log/app.log | grep -i error | while read line; do
  curl -d "$line" \
    -H "X-Title: Application Error" \
    -H "X-Priority: 4" \
    -H "X-Tags: logs,error" \
    https://app.notifer.io/app-errors
done

Health Check¶

#!/bin/bash
# Ping service and alert if down
if ! curl -sf https://myapp.com/health > /dev/null; then
  curl -d "Service health check failed!" \
    -H "X-Priority: 5" \
    -H "X-Tags: health,critical" \
    -H "X-Topic-Token: tk_your_token_here" \
    https://app.notifer.io/alerts
fi

Advanced Options¶

Rate Limiting¶

Respect rate limits by checking response headers:

curl -i -d "Message" https://app.notifer.io/topic

Response headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1699000000

Retry Logic¶

Implement exponential backoff for failed requests:

#!/bin/bash
MAX_RETRIES=3
RETRY_DELAY=1

for i in $(seq 1 $MAX_RETRIES); do
  if curl -d "Message" https://app.notifer.io/topic; then
    exit 0
  fi
  echo "Retry $i failed, waiting ${RETRY_DELAY}s"
  sleep $RETRY_DELAY
  RETRY_DELAY=$((RETRY_DELAY * 2))
done
echo "All retries failed"
exit 1

Next Steps¶

Python Publishing - Use Python SDK
JavaScript Publishing - Publish from Node.js or browser
CLI Tool - Command-line interface
API Keys - Manage authentication