Push alerts
Section titled “Push alerts”This page documents the computer’s Web Push routes for retrieving the VAPID public key, managing browser push subscriptions, and sending a fixed test alert. Use these endpoints when implementing device enrollment or troubleshooting push delivery. These are computer-scoped Kit routes, and access is controlled by the computer’s proxy permission rules.
GET /api/v1/notifications/push/vapid-public-key
Section titled “GET /api/v1/notifications/push/vapid-public-key”Returns the computer’s VAPID public key. Pass it to a page as applicationServerKey before calling pushManager.subscribe(). The key pair is created on first use and retained. It does not change while subscriptions exist.
This endpoint takes no path, query, or header parameters.
Request
Section titled “Request”curl --request GET \ --url 'https://{projectId}-{computerId}-n-1.{server}.computers.hoody.com/api/v1/notifications/push/vapid-public-key'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-n-1.{server}.computers.hoody.com' });
const publicKey = await client.notifications.push.getPublicKey();Response fields
Section titled “Response fields”Success response
Section titled “Success response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | Indicates that the request succeeded. |
data | object | Yes | Contains the public key. |
data.publicKey | string | Yes | Uncompressed P-256 public key, base64url without padding, 87 characters. |
Error response
Section titled “Error response”| Field | Type | Required | Description |
|---|---|---|---|
details | string | No | Detailed error message. |
error | string | Yes | Error type or category. |
code | string | No | Stable machine-readable error code. |
success | boolean | Yes | Indicates that the request failed. |
message | string | No | Human-readable explanation. |
Responses
Section titled “Responses”Media type: application/json
{ "success": true, "data": { "publicKey": "BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U" }}The request exceeded a fixed-window limit. The Retry-After response header contains whole seconds until the current window ends, rounded up, with a minimum of 1.
Media type: application/json
{ "success": false, "error": "Rate Limit Exceeded", "message": "You have exceeded the 60 requests in 1 minutes limit on this endpoint."}The push storage operation failed.
Media type: application/json
{ "success": false, "error": "Push storage failed", "code": "PUSH_STORAGE_FAILED", "details": "Push state could not be read or written."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
PUSH_STORAGE_FAILED | Push storage failed | Reading or writing the push storage directory failed. | Check that the push storage directory is writable, then retry |
Push is disabled, or its key is unavailable while subscriptions exist.
Media type: application/json
{ "success": false, "error": "Push disabled", "code": "PUSH_DISABLED", "details": "Phone and browser push is turned off on this computer."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
PUSH_DISABLED | Push disabled | PUSH_ENABLED is false on this server. | Turn push on with PUSH_ENABLED=true, or use the stream or history instead |
PUSH_UNAVAILABLE | Push unavailable | The server’s push key is missing or damaged while subscriptions bound to it exist. The key is never replaced on its own, since every stored subscription would stop working. | Remove subscriptions.json from the push storage directory and restart; open pages enroll again on their next visit |
GET /api/v1/notifications/push/subscriptions
Section titled “GET /api/v1/notifications/push/subscriptions”Lists every stored push subscription, oldest first, in one response, with delivery health. The subscription limit, PUSH_MAX_SUBSCRIPTIONS, defaults to 50 and is enforced when a subscription is created. Lowering the limit does not remove stored subscriptions, so the listed count can exceed the current limit.
Browser keys and full endpoint URLs are never returned. The summary instead includes the endpoint host, subscription origin, display selection, and recent delivery health.
This endpoint takes no path, query, or header parameters.
Request
Section titled “Request”curl --request GET \ --url 'https://{projectId}-{computerId}-n-1.{server}.computers.hoody.com/api/v1/notifications/push/subscriptions'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-n-1.{server}.computers.hoody.com' });
const subscriptions = await client.notifications.push.subscriptions.list();Response fields
Section titled “Response fields”Success response
Section titled “Success response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | Indicates that the request succeeded. |
data | object | Yes | Contains the subscription list. |
data.count | integer | Yes | Number of subscriptions listed. This can exceed data.max if the limit was lowered after subscriptions were stored. |
data.max | integer | Yes | Configured PUSH_MAX_SUBSCRIPTIONS value. The default is 50. Lowering this value does not remove stored subscriptions. |
data.subscriptions | array | Yes | Stored subscription summaries, ordered oldest first. |
data.subscriptions[].id | string | Yes | Subscription ID, 22 characters in base64url. |
data.subscriptions[].endpointHost | string | Yes | Host of the browser’s push service. |
data.subscriptions[].origin | string | Yes | Origin of the page that subscribed. Alert links open on this origin. |
data.subscriptions[].displays | string | array | Yes | "all" or the display numbers this device receives. |
data.subscriptions[].createdAt | integer | Yes | Subscription creation time in Unix milliseconds. |
data.subscriptions[].userAgent | string | null | No | Browser label supplied when the subscription was registered. |
data.subscriptions[].lastSuccessAt | integer | null | No | Last time the push service accepted a message, in Unix milliseconds. |
data.subscriptions[].lastFailureAt | integer | null | No | Last failed delivery time, in Unix milliseconds. |
data.subscriptions[].lastFailureStatus | integer | null | No | HTTP status of the last failed delivery. |
data.subscriptions[].consecutiveFailures | integer | Yes | Failed deliveries since the last success. A non-zero value places the device in a cooldown that starts at one minute after the last failure, doubles after each further failure, and is capped at one hour. Notifications received during a cooldown are skipped and never replayed, although history retains them. A success ends the cooldown, while a test push ignores it. |
Error response
Section titled “Error response”| Field | Type | Required | Description |
|---|---|---|---|
details | string | No | Detailed error message. |
error | string | Yes | Error type or category. |
code | string | No | Stable machine-readable error code. |
success | boolean | Yes | Indicates that the request failed. |
message | string | No | Human-readable explanation. |
Responses
Section titled “Responses”Media type: application/json
{ "success": true, "data": { "count": 1, "max": 50, "subscriptions": [ { "id": "q3F0b2tVc2VyQWdlbnQxMg", "endpointHost": "fcm.googleapis.com", "origin": "https://example.com", "displays": "all", "createdAt": 1760598000000, "userAgent": "Mozilla/5.0 (Linux; Android 15) Chrome/141.0", "lastSuccessAt": 1760598120000, "consecutiveFailures": 0 } ] }}The request exceeded a fixed-window limit. The Retry-After response header contains whole seconds until the current window ends, rounded up, with a minimum of 1.
Media type: application/json
{ "success": false, "error": "Rate Limit Exceeded", "message": "You have exceeded the 60 requests in 1 minutes limit on this endpoint."}The push storage operation failed.
Media type: application/json
{ "success": false, "error": "Push storage failed", "code": "PUSH_STORAGE_FAILED", "details": "Push state could not be read or written."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
PUSH_STORAGE_FAILED | Push storage failed | Reading or writing the push storage directory failed. | Check that the push storage directory is writable, then retry |
Push is disabled, or its key is unavailable while subscriptions exist.
Media type: application/json
{ "success": false, "error": "Push disabled", "code": "PUSH_DISABLED", "details": "Phone and browser push is turned off on this computer."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
PUSH_DISABLED | Push disabled | PUSH_ENABLED is false on this server. | Turn push on with PUSH_ENABLED=true, or use the stream or history instead |
PUSH_UNAVAILABLE | Push unavailable | The server’s push key is missing or damaged while subscriptions bound to it exist. The key is never replaced on its own, since every stored subscription would stop working. | Remove subscriptions.json from the push storage directory and restart; open pages enroll again on their next visit |
POST /api/v1/notifications/push/subscriptions
Section titled “POST /api/v1/notifications/push/subscriptions”Stores a browser push subscription so new notifications can reach that device while the page is closed. Send the fields produced by PushSubscription.toJSON().
Posting an endpoint that is already stored refreshes it and returns the subscription ID with a 200 response. When replacesEndpoint identifies a rotated endpoint, the existing record takes the new endpoint under the same ID and returns 200 with replaced: true. Rotation does not consume another subscription slot, but only an earlier record created from the same origin can be replaced. Otherwise, the route creates a new record and returns 201, unless PUSH_MAX_SUBSCRIPTIONS records are already stored.
Only endpoints belonging to browser push services are accepted. The allowed hosts are configured by PUSH_ALLOWED_ENDPOINT_HOSTS.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
Origin | header | string | Yes | Set by the browser. Must be an https origin. A null origin is refused. Alert links open on this origin. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
endpoint | string | Yes | Browser push service URL. Must be an https URI on a known push service host. Maximum size: 2048 bytes (UTF-8). |
keys | object | Yes | Browser encryption and authentication keys. |
keys.p256dh | string | Yes | Browser public key represented as an uncompressed P-256 point in base64url. |
keys.auth | string | Yes | Browser authentication secret represented as 16 bytes in base64url. |
userAgent | string | No | Label shown in the subscription list. Control characters are removed and the value is limited to 200 characters. Default: the User-Agent header. |
displays | string | array | No | Displays whose notifications reach this device. Default: "all". The value "*" is also accepted. Use a comma-separated string such as "1,2" or an array of display numbers. Each array entry is a one-to-five-digit string with an optional leading colon or an integer from 0 through 99999. The array must contain 1 to 100 entries. After duplicates are removed, either form selects at most 100 distinct displays. |
replacesEndpoint | string | null | No | The earlier endpoint replaced by this subscription. Maximum size: 2048 bytes (UTF-8). The earlier record must have been created from the same origin. |
{ "endpoint": "https://fcm.googleapis.com/fcm/send/dXJsLXNhZmUtdG9rZW4", "keys": { "p256dh": "BNcRdreALRFXTkOOUHK1EtK2wtaz5Ry4YfYCA_0QTpQtUbVlUls0VJXg7A8u-Ts1XbjhazAkj7I99e8QcYP7DkM", "auth": "tBHItJI5svbpez7KI4CCXg" }, "userAgent": "Pixel 9 / Chrome", "displays": "all"}Request
Section titled “Request”curl --request POST \ --url 'https://{projectId}-{computerId}-n-1.{server}.computers.hoody.com/api/v1/notifications/push/subscriptions' \ --header 'Content-Type: application/json' \ --header 'Origin: https://example.com' \ --data '{ "endpoint": "https://fcm.googleapis.com/fcm/send/dXJsLXNhZmUtdG9rZW4", "keys": { "p256dh": "BNcRdreALRFXTkOOUHK1EtK2wtaz5Ry4YfYCA_0QTpQtUbVlUls0VJXg7A8u-Ts1XbjhazAkj7I99e8QcYP7DkM", "auth": "tBHItJI5svbpez7KI4CCXg" }, "userAgent": "Pixel 9 / Chrome", "displays": "all" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-n-1.{server}.computers.hoody.com' });
const data = { endpoint: 'https://fcm.googleapis.com/fcm/send/dXJsLXNhZmUtdG9rZW4', keys: { p256dh: 'BNcRdreALRFXTkOOUHK1EtK2wtaz5Ry4YfYCA_0QTpQtUbVlUls0VJXg7A8u-Ts1XbjhazAkj7I99e8QcYP7DkM', auth: 'tBHItJI5svbpez7KI4CCXg' }, userAgent: 'Pixel 9 / Chrome', displays: 'all'};
const result = await client.notifications.push.subscriptions.create(data, { origin: 'https://example.com'});Response fields
Section titled “Response fields”Success response
Section titled “Success response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | Indicates that the request succeeded. |
data | object | Yes | Contains the subscription result. |
data.id | string | Yes | Subscription ID. |
data.created | boolean | Yes | Indicates whether a new record was created. |
data.replaced | boolean | Yes | Indicates whether the record of replacesEndpoint now holds this endpoint. |
Error response
Section titled “Error response”| Field | Type | Required | Description |
|---|---|---|---|
details | string | No | Detailed error message. |
error | string | Yes | Error type or category. |
code | string | No | Stable machine-readable error code. |
success | boolean | Yes | Indicates that the request failed. |
message | string | No | Human-readable explanation. |
Responses
Section titled “Responses”The endpoint was already stored and refreshed, or an earlier endpoint was replaced.
Media type: application/json
{ "success": true, "data": { "id": "q3F0b2tVc2VyQWdlbnQxMg", "created": false, "replaced": true }}A new subscription was created.
Media type: application/json
{ "success": true, "data": { "id": "q3F0b2tVc2VyQWdlbnQxMg", "created": true, "replaced": false }}The request is malformed, the Origin header is unusable, or the endpoint is not permitted.
Media type: application/json
{ "success": false, "error": "Validation Error", "code": "VALIDATION_ERROR", "details": "\"keys.auth\" must be 16 bytes of base64url"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
VALIDATION_ERROR | Invalid request | The body is not a JSON object, or a field is missing or malformed. | Send the fields of the browser’s PushSubscription.toJSON() as documented |
PUSH_ORIGIN_REQUIRED | Origin required | The Origin header is missing, null, or not an https origin. | Subscribe from the notifications page over https; the request needs its Origin header. |
PUSH_ENDPOINT_NOT_ALLOWED | Endpoint not allowed | The endpoint is not an https URL on a browser push service host (default port, no credentials, no IP address). | Send the endpoint the browser returned from pushManager.subscribe() |
The subscription limit has been reached.
Media type: application/json
{ "success": false, "error": "Subscription limit reached", "code": "PUSH_SUBSCRIPTION_LIMIT", "details": "This computer already holds the maximum number of push subscriptions; remove one first."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
PUSH_SUBSCRIPTION_LIMIT | Subscription limit reached | PUSH_MAX_SUBSCRIPTIONS subscriptions are stored (default 50). | Delete unused subscriptions with DELETE /push/subscriptions/{id}, then retry |
The request exceeded a fixed-window limit. The Retry-After response header contains whole seconds until the current window ends, rounded up, with a minimum of 1.
Media type: application/json
{ "success": false, "error": "Rate Limit Exceeded", "message": "You have exceeded the 60 requests in 1 minutes limit on this endpoint."}The push storage operation failed.
Media type: application/json
{ "success": false, "error": "Push storage failed", "code": "PUSH_STORAGE_FAILED", "details": "Push state could not be read or written."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
PUSH_STORAGE_FAILED | Push storage failed | Reading or writing the push storage directory failed. | Check that the push storage directory is writable, then retry |
Push is disabled, or its key is unavailable while subscriptions exist.
Media type: application/json
{ "success": false, "error": "Push disabled", "code": "PUSH_DISABLED", "details": "Phone and browser push is turned off on this computer."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
PUSH_DISABLED | Push disabled | PUSH_ENABLED is false on this server. | Turn push on with PUSH_ENABLED=true, or use the stream or history instead |
PUSH_UNAVAILABLE | Push unavailable | The server’s push key is missing or damaged while subscriptions bound to it exist. The key is never replaced on its own, since every stored subscription would stop working. | Remove subscriptions.json from the push storage directory and restart; open pages enroll again on their next visit |
DELETE /api/v1/notifications/push/subscriptions/{id}
Section titled “DELETE /api/v1/notifications/push/subscriptions/{id}”Removes one stored subscription. The device receives no more alerts through that subscription until its page subscribes again.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Subscription ID returned by the list operation. |
Request
Section titled “Request”curl --request DELETE \ --url 'https://{projectId}-{computerId}-n-1.{server}.computers.hoody.com/api/v1/notifications/push/subscriptions/q3F0b2tVc2VyQWdlbnQxMg'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-n-1.{server}.computers.hoody.com' });
const id = 'q3F0b2tVc2VyQWdlbnQxMg';const result = await client.notifications.push.subscriptions.delete(id);Response fields
Section titled “Response fields”Error response
Section titled “Error response”| Field | Type | Required | Description |
|---|---|---|---|
details | string | No | Detailed error message. |
error | string | Yes | Error type or category. |
code | string | No | Stable machine-readable error code. |
success | boolean | Yes | Indicates that the request failed. |
message | string | No | Human-readable explanation. |
Responses
Section titled “Responses”Media type: none
The subscription was deleted and the response has no body.
No stored subscription has the supplied ID.
Media type: application/json
{ "success": false, "error": "Not Found", "code": "PUSH_SUBSCRIPTION_NOT_FOUND", "details": "No push subscription has this id."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
PUSH_SUBSCRIPTION_NOT_FOUND | Subscription not found | No stored subscription has this id (it was removed, or expired at the push service). | List subscriptions for current ids, or subscribe again |
The request exceeded a fixed-window limit. The Retry-After response header contains whole seconds until the current window ends, rounded up, with a minimum of 1.
Media type: application/json
{ "success": false, "error": "Rate Limit Exceeded", "message": "You have exceeded the 60 requests in 1 minutes limit on this endpoint."}The push storage operation failed.
Media type: application/json
{ "success": false, "error": "Push storage failed", "code": "PUSH_STORAGE_FAILED", "details": "Push state could not be read or written."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
PUSH_STORAGE_FAILED | Push storage failed | Reading or writing the push storage directory failed. | Check that the push storage directory is writable, then retry |
Push is disabled, or its key is unavailable while subscriptions exist.
Media type: application/json
{ "success": false, "error": "Push disabled", "code": "PUSH_DISABLED", "details": "Phone and browser push is turned off on this computer."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
PUSH_DISABLED | Push disabled | PUSH_ENABLED is false on this server. | Turn push on with PUSH_ENABLED=true, or use the stream or history instead |
PUSH_UNAVAILABLE | Push unavailable | The server’s push key is missing or damaged while subscriptions bound to it exist. The key is never replaced on its own, since every stored subscription would stop working. | Remove subscriptions.json from the push storage directory and restart; open pages enroll again on their next visit |
POST /api/v1/notifications/push/test
Section titled “POST /api/v1/notifications/push/test”Sends a fixed test alert to one subscription or to all subscriptions. The test ignores delivery cooldowns and reports the push services’ responses within 20 seconds.
An accepted result means the push service took the message, not that the device displayed it. If the push service reports that a subscription is gone, the subscription is deleted and counted in removed.
This route uses the RATE_LIMIT_NOTIFY_MAX budget, which defaults to 10 requests per window and is counted separately from POST /notify.
This endpoint takes no path, query, or header parameters.
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
subscriptionId | string | null | No | Sends the test only to this subscription. Omit it or send null to send the test to all subscriptions. |
{ "subscriptionId": "q3F0b2tVc2VyQWdlbnQxMg"}Request
Section titled “Request”curl --request POST \ --url 'https://{projectId}-{computerId}-n-1.{server}.computers.hoody.com/api/v1/notifications/push/test' \ --header 'Content-Type: application/json' \ --data '{ "subscriptionId": "q3F0b2tVc2VyQWdlbnQxMg" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-n-1.{server}.computers.hoody.com' });
const data = { subscriptionId: 'q3F0b2tVc2VyQWdlbnQxMg'};
const result = await client.notifications.push.test(data);Response fields
Section titled “Response fields”Success response
Section titled “Success response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | Indicates that the test request completed. |
data | object | Yes | Contains the delivery results. |
data.accepted | integer | Yes | Messages accepted by the push service. Acceptance does not confirm that the device displayed the alert. |
data.failed | integer | Yes | Messages refused by the push service, retried out, or not sent. |
data.removed | integer | Yes | Subscriptions reported as gone by the push service and deleted. |
data.pending | integer | Yes | Deliveries unfinished at the 20-second mark, whether queued, in progress, or retrying. They finish in the background. |
Error response
Section titled “Error response”| Field | Type | Required | Description |
|---|---|---|---|
details | string | No | Detailed error message. |
error | string | Yes | Error type or category. |
code | string | No | Stable machine-readable error code. |
success | boolean | Yes | Indicates that the request failed. |
message | string | No | Human-readable explanation. |
Responses
Section titled “Responses”Media type: application/json
{ "success": true, "data": { "accepted": 1, "failed": 0, "removed": 0, "pending": 0 }}The body is not valid JSON or is not a JSON object, or a non-null subscriptionId is not a string. An empty body, {}, or {"subscriptionId": null} sends to all subscriptions.
Media type: application/json
{ "success": false, "error": "Validation Error", "code": "VALIDATION_ERROR", "details": "\"subscriptionId\" must be a string"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
VALIDATION_ERROR | Invalid request | The body is not valid JSON or not a JSON object, or a non-null subscriptionId is not a string. An empty body, {}, or {"subscriptionId": null} sends to all subscriptions. | Send {} or {"subscriptionId": "<id>"} |
No stored subscription has the supplied ID.
Media type: application/json
{ "success": false, "error": "Not Found", "code": "PUSH_SUBSCRIPTION_NOT_FOUND", "details": "No push subscription has this id."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
PUSH_SUBSCRIPTION_NOT_FOUND | Subscription not found | No stored subscription has this id (it was removed, or expired at the push service). | List subscriptions for current ids, or subscribe again |
The request exceeded a fixed-window limit. The Retry-After response header contains whole seconds until the current window ends, rounded up, with a minimum of 1.
Media type: application/json
{ "success": false, "error": "Rate Limit Exceeded", "message": "You have exceeded the 60 requests in 1 minutes limit on this endpoint."}The push storage operation failed.
Media type: application/json
{ "success": false, "error": "Push storage failed", "code": "PUSH_STORAGE_FAILED", "details": "Push state could not be read or written."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
PUSH_STORAGE_FAILED | Push storage failed | Reading or writing the push storage directory failed. | Check that the push storage directory is writable, then retry |
Push is disabled, or its key is unavailable while subscriptions exist.
Media type: application/json
{ "success": false, "error": "Push disabled", "code": "PUSH_DISABLED", "details": "Phone and browser push is turned off on this computer."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
PUSH_DISABLED | Push disabled | PUSH_ENABLED is false on this server. | Turn push on with PUSH_ENABLED=true, or use the stream or history instead |
PUSH_UNAVAILABLE | Push unavailable | The server’s push key is missing or damaged while subscriptions bound to it exist. The key is never replaced on its own, since every stored subscription would stop working. | Remove subscriptions.json from the push storage directory and restart; open pages enroll again on their next visit |