← Back to Docs
Notification Streams
Pub/sub notification channels with shareable codes
How it works
- 1. Create a stream via the API — you get a short code like
DEPLOY-XK3 - 2. Share the code with anyone — clients, team members, users
- 3. They enter the code in the notfs app to subscribe
- 4. Send a notification to the stream — all subscribers receive it instantly
Create a Stream
POST /api/streams
curl -X POST https://api.notfs.dev/api/streams \
-H "X-API-Key: ntfs_your_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Deploy Alerts",
"description": "Production deployment notifications"
}'Response (201)
{
"id": "clx...",
"name": "Deploy Alerts",
"code": "DEPLOY-XK3",
"description": "Production deployment notifications",
"iconUrl": null,
"subscribers": 0,
"createdAt": "2026-02-20T03:00:00.000Z"
}Send to Stream
POST /api/streams/:id/send
curl -X POST https://api.notfs.dev/api/streams/STREAM_ID/send \
-H "X-API-Key: ntfs_your_key" \
-H "Content-Type: application/json" \
-d '{
"title": "v2.4.1 deployed",
"body": "Production is live",
"priority": "high"
}'Response
{
"notificationId": "clx...",
"sent": 12,
"subscribers": 12,
"stream": {
"name": "Deploy Alerts",
"code": "DEPLOY-XK3"
}
}All Endpoints
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| POST | /api/streams | Create a new stream | API Key (notifications:write) |
| GET | /api/streams | List your streams | API Key or JWT |
| DELETE | /api/streams/:id | Delete a stream | API Key or JWT |
| POST | /api/streams/:id/send | Send to all subscribers | API Key (notifications:write) |
| POST | /api/streams/subscribe | Subscribe by code | JWT |
| GET | /api/streams/subscriptions | List subscriptions | JWT |
| DELETE | /api/streams/subscriptions/:id | Unsubscribe | JWT |
| GET | /api/streams/lookup/:code | Lookup stream by code | JWT |
Create Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | yes | Stream name (1-50 chars) |
| description | string | no | Short description (max 200 chars) |
| iconUrl | string | no | Icon URL for the stream |
Send Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| title | string | yes | Notification title |
| body | string | no | Notification body |
| sound | enum | no | default, soft, critical |
| priority | enum | no | low, normal, high, critical |
| senderName | string | no | Override stream name as sender |
| senderIcon | string | no | Override stream icon |
Limits
- • Free plan: 3 streams
- • Pro plan: Unlimited streams
- • Stream codes are auto-generated and unique
- • Creators cannot subscribe to their own streams