Save this browser's push subscription

me.push_subscription.put

PUT/api/v1/me/push-subscription

Route

Saves the browser's web push subscription for your current session, replacing any subscription with the same endpoint (even one saved by another account or session on this browser). Signing out, or the session ending, removes it, which stops pushes to that device. The web app sends this each time it starts with notification permission granted. Fails with validation_failed when the endpoint isn't on an allowed push service or the keys are malformed; nothing is saved then.

Request body#

JSON, as application/json.

Save this browser's push subscription: request body fields
Field	Description
`endpoint`stringrequired	The push service URL from the browser's PushSubscription. It must be on a known push service (Google, Mozilla, Apple or Microsoft) and use https. at most 2,048 characters
`keys`objectrequired
`keys.p256dh`stringrequired	The browser's public key, base64url without padding: 65 bytes, an uncompressed P-256 point.
`keys.auth`stringrequired	The browser's auth secret, base64url without padding: 16 bytes.

Response#

204 Saved. No body.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

Save this browser's push subscription: errors
Status	Code	When
`400`	`validation_failed`	A field is missing, misspelled or out of range. details.fields lists each problem.
`401`	Read error.code	Described above.
`401`	`unauthenticated`	The request has no valid session.

Examples#

These are real. Each was recorded from a sample household, the Okafors, running through the whole API when this site was built.

Save this browser's push subscription

Send what the browser's PushSubscription gives you. The web app does this each time it starts with permission granted.

Request, curl

curl -X PUT 'https://rigel.house/api/v1/me/push-subscription' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -d '{
  "endpoint": "https://fcm.googleapis.com/fcm/send/dQw4w9WgXcQ:APA91bHn7s3kT0example",
  "keys": {
    "p256dh": "BMJO8Dn_95DrDH1P3bT_1IgPDEbKjSG95zGI54d3QbA-LmMeASZFsDREyI40wvBcZvWa_Rk7lyKkNSF7Zb0kWT4",
    "auth": "CQhJckRhVYSzvXnOc3josQ"
  }
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/me/push-subscription", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    endpoint: "https://fcm.googleapis.com/fcm/send/dQw4w9WgXcQ:APA91bHn7s3kT0example",
    keys: {
      p256dh: "BMJO8Dn_95DrDH1P3bT_1IgPDEbKjSG95zGI54d3QbA-LmMeASZFsDREyI40wvBcZvWa_Rk7lyKkNSF7Zb0kWT4",
      auth: "CQhJckRhVYSzvXnOc3josQ",
    },
  }),
});
const data = await response.json();

Request, HTTP

PUT /api/v1/me/push-subscription HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/dQw4w9WgXcQ:APA91bHn7s3kT0example",
  "keys": {
    "p256dh": "BMJO8Dn_95DrDH1P3bT_1IgPDEbKjSG95zGI54d3QbA-LmMeASZFsDREyI40wvBcZvWa_Rk7lyKkNSF7Zb0kWT4",
    "auth": "CQhJckRhVYSzvXnOc3josQ"
  }
}

Response, 204

HTTP/1.1 204 No Content
X-Request-Id: req_01M6V9CSTAA04HGW39MBW0TPZF

A push endpoint that isn't a known push service

Request, curl

curl -X PUT 'https://rigel.house/api/v1/me/push-subscription' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -d '{
  "endpoint": "https://push.example.com/send/abc",
  "keys": {
    "p256dh": "BMJO8Dn_95DrDH1P3bT_1IgPDEbKjSG95zGI54d3QbA-LmMeASZFsDREyI40wvBcZvWa_Rk7lyKkNSF7Zb0kWT4",
    "auth": "CQhJckRhVYSzvXnOc3josQ"
  }
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/me/push-subscription", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    endpoint: "https://push.example.com/send/abc",
    keys: {
      p256dh: "BMJO8Dn_95DrDH1P3bT_1IgPDEbKjSG95zGI54d3QbA-LmMeASZFsDREyI40wvBcZvWa_Rk7lyKkNSF7Zb0kWT4",
      auth: "CQhJckRhVYSzvXnOc3josQ",
    },
  }),
});
const data = await response.json();

Request, HTTP

PUT /api/v1/me/push-subscription HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json

{
  "endpoint": "https://push.example.com/send/abc",
  "keys": {
    "p256dh": "BMJO8Dn_95DrDH1P3bT_1IgPDEbKjSG95zGI54d3QbA-LmMeASZFsDREyI40wvBcZvWa_Rk7lyKkNSF7Zb0kWT4",
    "auth": "CQhJckRhVYSzvXnOc3josQ"
  }
}

Response, 400

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Request-Id: req_01M6V9CSTBDJ0EQ0GMR1WZWJKT

{
  "error": {
    "code": "validation_failed",
    "message": "The request has invalid fields. No changes were applied.",
    "details": {
      "fields": [
        {
          "field": "endpoint",
          "problem": "must be an https URL on a known push service (Google, Mozilla, Apple or Microsoft)"
        }
      ]
    },
    "recovery": "Correct each field listed in details.fields, then send the request again.",
    "request_id": "req_01M6V9CSTBDJ0EQ0GMR1WZWJKT"
  }
}