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
| Status | Meaning | Body |
|---|---|---|
| 200 | Settings. | Config |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Config
| Field | Type | Description |
|---|---|---|
enabled (required) | boolean | Enabled is false when the operator turned push off (PUSH_ENABLED=false). |
max_devices (required) | integer | MaxDevices is how many devices one account may enable push on. |
preview (required) | boolean | Preview is the member's choice: include the message text in pushes. Only takes effect while PreviewAllowed. |
preview_allowed (required) | boolean | PreviewAllowed is false when the operator forces pushes without message text. |
public_key (required) | string | PublicKey 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
| Field | Type | Description |
|---|---|---|
preview (required) | boolean | Preview includes the message text in pushes (default true). |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: push is turned off on this server. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Status | Meaning | Body |
|---|---|---|
| 200 | Devices. | Subscriptions |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: push is turned off on this server. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Subscriptions
| Field | Type | Description |
|---|---|---|
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
| Field | Type | Description |
|---|---|---|
auth (required) | string | Auth is the browser's 16 byte authentication secret, base64url. |
endpoint (required) | string | Endpoint is the push service address the browser got. https only, a public host, port 443. |
label | string | Label names the device in the list ("Firefox on Windows"); at most 64 characters. |
p256dh (required) | string | P256dh is the browser's P-256 public key, base64url. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | Registered. | Subscription |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, a refused endpoint or invalid keys. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: push is turned off on this server. | ErrorResponse |
| 409 | CONFLICT: the account already has 10 devices. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
Subscription
| Field | Type | Description |
|---|---|---|
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Subscription ID. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 204 | Success, no content. | |
| 400 | Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation. | ErrorResponse |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: the resource, or the route, does not exist. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_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
| Status | Meaning | Body |
|---|---|---|
| 200 | Result. | TestResult |
| 401 | No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled. | ErrorResponse |
| 404 | NOT_FOUND: push is turned off on this server. | ErrorResponse |
| 429 | RATE_LIMITED: too many requests. | ErrorResponse |
| 500 | INTERNAL_ERROR: sanitized server failure. | ErrorResponse |
TestResult
| Field | Type | Description |
|---|---|---|
delivered (required) | integer | |
failed (required) | integer |