REST: Push

Web Push: the server's public key, a device's subscriptions, preferences and a test notification. Generated from mnema-talk v3.3.13 (cca4f0fdb723).

Web Push settings

GET /api/push/config

Whether push is on, the VAPID public key to subscribe with, whether the operator allows message text in pushes and the caller's own choice. Always answers 200; with push off the key is empty.

Authentication: Session cookie

Responses

StatusMeaningBody
200Settings.Config
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Config
FieldTypeDescription
enabled (required)booleanEnabled is false when the operator turned push off (PUSH_ENABLED=false).
max_devices (required)integerMaxDevices is how many devices one account may enable push on.
preview (required)booleanPreview is the member's choice: include the message text in pushes. Only takes effect while PreviewAllowed.
preview_allowed (required)booleanPreviewAllowed is false when the operator forces pushes without message text.
public_key (required)stringPublicKey is the VAPID public key (base64url) to subscribe with; empty while push is off.

Set the push preview

PUT /api/push/preferences

Whether pushes carry the message text. Off, a push shows only the channel and the sender. The operator can force this off for everyone (PUSH_PREVIEWS=off); the stored choice is kept.

Authentication: Session cookie

Request body (application/json, required): PreferencesRequest

FieldTypeDescription
preview (required)booleanPreview includes the message text in pushes (default true).

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: push is turned off on this server.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

List my push devices

GET /api/push/subscriptions

The caller's devices with push on, oldest first. The push address itself is never returned; fingerprint is the first 32 hex characters of the SHA-256 of the endpoint, so a browser can tell which entry is itself.

Authentication: Session cookie

Responses

StatusMeaningBody
200Devices.Subscriptions
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: push is turned off on this server.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Subscriptions
FieldTypeDescription
subscriptions (required)Subscription[]

Turn push on for this device

POST /api/push/subscriptions

Registers the browser's push subscription for the caller. The endpoint must be an https URL on port 443 whose host is not a literal private, loopback or reserved address; the server connects only to that address, only to deliver encrypted pushes. Registering an endpoint again updates it; one registered by another account moves to the caller. At most 10 devices per account.

Authentication: Session cookie

Request body (application/json, required): SubscribeRequest

FieldTypeDescription
auth (required)stringAuth is the browser's 16 byte authentication secret, base64url.
endpoint (required)stringEndpoint is the push service address the browser got. https only, a public host, port 443.
labelstringLabel names the device in the list ("Firefox on Windows"); at most 64 characters.
p256dh (required)stringP256dh is the browser's P-256 public key, base64url.

Responses

StatusMeaningBody
201Registered.Subscription
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, a refused endpoint or invalid keys.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: push is turned off on this server.ErrorResponse
409CONFLICT: the account already has 10 devices.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Subscription
FieldTypeDescription
created_at (required)string (date-time)
fingerprint (required)string
id (required)string (uuid)
label (required)string
last_success_at (required)string | null

Turn push off for a device

DELETE /api/push/subscriptions/{id}

Removes one of the caller's devices. Another account's device answers 404 like a missing one.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesSubscription ID.

Responses

StatusMeaningBody
204Success, no content.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Send a test push

POST /api/push/test

Sends a test notification to every device of the caller and reports how many push services accepted it. At most 6 a minute.

Authentication: Session cookie

Responses

StatusMeaningBody
200Result.TestResult
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: push is turned off on this server.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
TestResult
FieldTypeDescription
delivered (required)integer
failed (required)integer

Something wrong on this page? Tell us.