Skip to content
Subscribers and topics

Subscribers and topics

All routes take an API key.

Subscribers

Method and pathPurposeSuccess
POST /v1/subscribersUpsert by subscriberId.201 the subscriber
GET /v1/subscribersList. ?after=<cursor>&limit=<n> (limit must be a positive integer).200 {data, next?, totalCount}
GET /v1/subscribers/{id}One subscriber, by internal id.200; 404
PATCH /v1/subscribers/{id}Update by internal id. Only fields present and non-empty are applied.200
DELETE /v1/subscribers/{id}Soft delete, by internal id.204; 404
POST /v1/subscribers/{subscriberId}/phone/consentAttest SMS consent for the subscriber’s phone. See operator-attested consent.201; 403 when not allowed; 404; 409 when they verified another number
DELETE /v1/subscribers/{subscriberId}/phone/consentRevoke an operator attestation.204; 404
POST /v1/subscribers/{subscriberId}/sessionMint a session token.200 {token, expiresAt}; 404 if the subscriber does not exist
PUT /v1/subscribers/{subscriberId}/credentialsSet the subscriber’s address for a provider.204
DELETE /v1/subscribers/{subscriberId}/credentials/webpush?endpoint=Remove one Web Push device.204; 400 without endpoint; 404
GET /v1/subscribers/{id}/preferencesPreferences. {id} is your subscriberId.200
PUT /v1/subscribers/{id}/preferencesPartially update them.200; 404; 422

The subscriber object:

{ "id": "01J…", "subscriberId": "user-1", "email": "", "phone": "+15551112222", "phoneVerified": true, "phoneConsent": "self_verified",
  "firstName": "", "lastName": "", "locale": "", "timezone": "", "data": { } }

POST and PATCH bodies take the same fields without id, phoneVerified and phoneConsent. Both are read-only: only the subscriber can verify a phone, and only an attestation makes it operator_attested. phoneConsent is absent when the phone has neither. A phone you write is stored without consent, and writing a different number clears consent of either kind; sms steps send only to a consented phone. Validation (a malformed email, an oversized field, too many or invalid custom data fields) is 400 with the reason.

PUT .../credentials takes {"providerId": "ntfy", "channel": "push", "credentials": { … }}; providerId is required. With providerId: "webpush", credentials is a browser PushSubscription (endpoint, keys.p256dh, keys.auth required). See push and chat for the fields.

Topics

Method and pathPurposeSuccess
POST /v1/topicsCreate or upsert {"key", "name"}.201 the topic; 422 for an invalid key
GET /v1/topicsList.200 {data: […]}
GET /v1/topics/{key}One topic.200 {id, key, name, memberCount}; 404
PUT /v1/topics/{key}Rename: body {"name"} (required). Creates the topic if missing.200
DELETE /v1/topics/{key}Delete the topic and its memberships.204; 404
POST /v1/topics/{key}/subscribersAdd {"subscriberId"}. The subscriber must exist.204; 400 empty; 404 unknown topic; 422 unknown subscriber
DELETE /v1/topics/{key}/subscribers/{subscriberId}Remove a member. Removing a non-member is not an error.204; 404 unknown topic