REST API

REST API

Server-to-server API for your backend. Send pushes, manage user tags, read a user's message history and record custom events — all via HTTP.

Authentication

All requests below require the app's secret API key passed as a request header:

http
X-API-Key: notirix_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Find your API key in Admin → Settings → API Key.

⚠️
The secret key gives full access to your app. Use it only on your server — never in browser JavaScript, HTML or a mobile app. Mobile apps use the separate public key (notirix_pub_…), which works only for device registration — see Mobile SDK.
Base URL
https://push.notirix.com/api/apps/:appId
Content type
application/json

All paths below are relative to the base URL.

CodeMeaning
200 / 201Success
400Bad request — check the request body and required fields
401Missing or invalid API key
402Plan limit reached (e.g. monthly message limit)
403The API key does not belong to this app, or the app is disabled
404User, message or other resource not found
429Too many requests — retry later
💡
Errors return JSON with a message field describing the problem.

Messages

Send push notifications to one user or to an audience built from segments. Title, body, URL, image and buttons support personalization variables such as {{ tag.KEY }} and {{ user.externalId }}.

POST/messagesSend to a user

Send a push notification to one user on all their active devices (web and mobile). Add scheduledAt to deliver it later.

http
POST /api/apps/YOUR_APP_ID/messages
X-API-Key: notirix_xxx
Content-Type: application/json

{
  "title": "Your order has shipped",
  "body": "Estimated delivery: tomorrow",
  "url": "https://example.com/orders/1042",
  "userId": "NOTIRIX_USER_ID",
  "tag": "orders"
}
POST/messages/broadcastBroadcast

Send a push notification to the users of the include segments minus the exclude segments. Without segments the message goes to all active users of the app.

http
POST /api/apps/YOUR_APP_ID/messages/broadcast
X-API-Key: notirix_xxx
Content-Type: application/json

{
  "title": "Flash sale — 30% off today only",
  "body": "Use code FLASH30 at checkout",
  "url": "https://example.com/sale",
  "image": "https://example.com/sale-banner.jpg",
  "buttons": [
    { "title": "Shop now", "url": "https://example.com/sale" },
    { "title": "My cart",  "url": "https://example.com/cart" }
  ],
  "includeSegmentIds": ["SEGMENT_ID"],
  "excludeSegmentIds": [],
  "scheduledAt": "2026-12-01T10:00:00Z",
  "tag": "promo"
}
GET/messages/feedMessage feed

Sent messages of the app, newest first — for example, to show a news feed on your site. Filter by one or several tags (comma-separated). limit defaults to 50 (max 500), offset to 0.

http
GET /api/apps/YOUR_APP_ID/messages/feed?tag=promo,news&limit=20&offset=0
X-API-Key: notirix_xxx

// Response
{
  "data": [
    { "id": "…", "title": "…", "body": "…", "url": "…", "image": null,
      "buttons": null, "tag": "promo", "createdAt": "2026-10-01T09:00:00.000Z" }
  ],
  "total": 42
}

Message fields

FieldTypeDescription
titlestringNotification title, required, up to 120 characters.
bodystringNotification text, required, up to 1024 characters.
urlstring?Page opened on click.
imagestring?Large image URL.
buttonsarray?Up to 2 action buttons: [{ "title", "url" }], title up to 40 characters. Safari and Firefox desktop show the notification without buttons.
userIdstringPOST /messages only, required. Notirix user ID (not your external ID) — get it from GET /users/external/:externalId.
includeSegmentIdsstring[]?Broadcast only. Users from any of these segments receive the message.
excludeSegmentIdsstring[]?Broadcast only. Users from these segments are removed from the audience.
scheduledAtstring?ISO 8601 date-time in the future. Omit to send immediately.
tagstring?Category of the message, up to 100 characters. Used to filter the message feed, a user's message history and unread counters.

Users

Users are created automatically when a browser or device subscribes. Link them to your accounts with an external ID (your own user ID) set in the SDK.

GET/users/external/:externalIdGet user by external ID

Returns the user's Notirix ID, status, dates and tags. Use the returned id as userId when sending a message.

http
GET /api/apps/YOUR_APP_ID/users/external/user-42
X-API-Key: notirix_xxx

// Response
{
  "id": "NOTIRIX_USER_ID",
  "externalId": "user-42",
  "status": "active",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "lastSeenAt": "2026-10-01T10:30:00.000Z",
  "userTags": [{ "key": "plan", "value": "premium" }]
}
GET/users/:id/publicGet user by Notirix ID

Same profile, looked up by the Notirix user ID.

DELETE/users/:idUnsubscribe user

Marks the user (by Notirix ID) as unsubscribed — they stop receiving push notifications. Subscriptions are kept: a new subscription from another browser or device makes the user active again; re-sending an existing one does not. This is not a deletion: to erase a user's data completely (GDPR), use the user page in the Admin panel.

Tags

Tags are key → value pairs on a user, used in segment rules and personalization. One key holds one value per user; writing an existing key overwrites it. Values may be strings, numbers, booleans or arrays.

POST/users/external/:externalId/tags/bulkSet tags by external ID

Upsert several tags at once. An unknown external ID is ignored ({ "created": 0 }).

http
POST /api/apps/YOUR_APP_ID/users/external/user-42/tags/bulk
X-API-Key: notirix_xxx
Content-Type: application/json

{
  "tags": {
    "plan": "premium",
    "total_orders": 14,
    "interests": ["sports", "tech"]
  }
}
GET/users/external/:externalId/tagsGet tags by external ID

Returns [{ "key", "value" }, …]. 404 if the user is not found.

POST/users/:id/tagsSet one tag by Notirix ID

Body: { "key": "plan", "value": "premium" }.

POST/users/:id/tags/bulkSet tags by Notirix ID

Same body as the external-ID variant.

GET/users/:id/tagsGet tags by Notirix ID

Returns [{ "key", "value" }, …].

Message history

Build an in-site notification center: list the messages a user received, show an unread badge and mark messages as read. A message counts as read once it was clicked or marked as read.

GET/users/external/:externalId/messagesUser's messages

Messages delivered to the user, newest first. Query: limit (default 20, max 100), offset, tag; with includeNullTag=1 messages without a tag are returned too. readAt is null while the message is unread.

http
GET /api/apps/YOUR_APP_ID/users/external/user-42/messages?limit=20&tag=orders
X-API-Key: notirix_xxx

// Response
{
  "data": [
    { "id": "MESSAGE_ID", "title": "…", "body": "…", "url": "…", "image": null,
      "buttons": null, "tag": "orders",
      "sentAt": "2026-10-01T09:00:00.000Z", "readAt": null }
  ],
  "total": 7
}
GET/users/external/:externalId/messages/unread-countUnread count

Returns { "count": 3 }. Optional ?tag= filter. An unknown external ID returns 0.

POST/users/external/:externalId/messages/:messageId/readMark as read

Marks the message as read on all of the user's devices. Returns { "updated": 1, "unreadCount": 2 }; unreadCount is null when nothing changed.

Custom events

Record an event that happened to a user on your side (purchase, sign-up, …). Journeys use custom events in the exit rule "Custom event": a user leaves the journey once the event arrives. Events are kept for 90 days.

POST/users/external/:externalId/eventsTrack event

Event name: 1–100 characters — letters, digits, "_", "-", ".", ":". Returns { "ok": true }, or { "ok": false } when the external ID is unknown. In the browser use sendEvent() from the Web SDK instead.

http
POST /api/apps/YOUR_APP_ID/users/external/user-42/events
X-API-Key: notirix_xxx
Content-Type: application/json

{ "name": "purchase" }
ℹ️
Segments, journeys, message templates and analytics are managed in the Admin panel and are not available with the API key. Create a segment in Admin → Segments and pass its ID in includeSegmentIds / excludeSegmentIds.