Mastodon
  • What is Mastodon?
  • Using Mastodon
    • Signing up for an account
    • Setting up your profile
    • Posting to your profile
    • Using the network features
    • Dealing with unwanted content
    • Promoting yourself and others
    • Set your preferences
    • More settings
    • Using Mastodon externally
    • Moving or leaving accounts
    • Running your own server
  • Running Mastodon
    • Preparing your machine
    • Installing from source
    • Configuring your environment
    • Configuring full-text search
    • Installing optional features
      • Object storage
      • Onion services
      • Captcha
      • Single Sign On
    • Setting up your new instance
    • Using the admin CLI
    • Upgrading to a new release
    • Backing up your server
    • Migrating to a new machine
    • Scaling up your server
    • Moderation actions
    • Troubleshooting errors
      • Database index corruption
    • Roles
  • Developing Mastodon apps
    • Getting started with the API
    • Playing with public data
    • Obtaining client app access
    • Logging in with an account
    • Libraries and implementations
  • Contributing to Mastodon
    • Technical overview
    • Setting up a dev environment
    • Code structure
    • Routes
    • Bug bounties and responsible disclosure
  • Spec compliance
    • ActivityPub
    • WebFinger
    • Security
    • Microformats
    • OAuth
    • Bearcaps
  • REST API
    • Datetime formats
    • Guidelines and best practices
    • OAuth Tokens
    • OAuth Scopes
    • Rate limits
  • API Methods
    • apps
      • oauth
      • emails
    • accounts
      • bookmarks
      • favourites
      • mutes
      • blocks
      • domain_blocks
      • filters
      • reports
      • follow_requests
      • endorsements
      • featured_tags
      • preferences
      • followed_tags
      • suggestions
      • tags
    • profile
    • statuses
      • media
      • polls
      • scheduled_statuses
    • timelines
      • conversations
      • lists
      • markers
      • streaming
    • grouped notifications
    • notifications
      • push
    • search
    • instance
      • trends
      • directory
      • custom_emojis
      • announcements
    • admin
      • accounts
      • canonical_email_blocks
      • dimensions
      • domain_allows
      • domain_blocks
      • email_domain_blocks
      • ip_blocks
      • measures
      • reports
      • retention
      • trends
    • proofs
    • oembed
  • API Entities
    • Account
    • AccountWarning
    • Admin::Account
    • Admin::CanonicalEmailBlock
    • Admin::Cohort
    • Admin::Dimension
    • Admin::DomainAllow
    • Admin::DomainBlock
    • Admin::EmailDomainBlock
    • Admin::Ip
    • Admin::IpBlock
    • Admin::Measure
    • Admin::Report
    • Announcement
    • Appeal
    • Application
    • Context
    • Conversation
    • CustomEmoji
    • DomainBlock
    • Error
    • ExtendedDescription
    • FamiliarFollowers
    • FeaturedTag
    • Filter
    • FilterKeyword
    • FilterResult
    • FilterStatus
    • IdentityProof
    • Instance
    • List
    • Marker
    • MediaAttachment
    • Notification
    • NotificationPolicy
    • NotificationRequest
    • Poll
    • Preferences
    • PreviewCard
    • PreviewCardAuthor
    • PrivacyPolicy
    • Quote
    • Reaction
    • Relationship
    • RelationshipSeveranceEvent
    • Report
    • Role
    • Rule
    • ScheduledStatus
    • Search
    • ShallowQuote
    • Status
    • StatusEdit
    • StatusSource
    • Suggestion
    • Tag
    • TermsOfService
    • Token
    • Translation
    • V1::Filter
    • V1::Instance
    • V1::NotificationPolicy
    • WebPushSubscription

push API methods

Subscribe to and receive push notifications when a server-side notification is received, via the Web Push API

    • About the Web Push API
    • Subscribe to push notifications
    • Get current subscription
    • Change types of notifications
    • Remove current subscription
    • See also

About the Web Push API

Mastodon natively supports the Web Push API. You can utilize the same mechanisms for your native app. Mastodon doesn’t connect to Android’s and Apple’s proprietary notification gateways directly, so if you wish to use those you can use a proxy server that translates between the WebPush standard and those gateways. This can be implemented in such a way that the proxy server does not have access to the contents of the notifications. For an example, see Mozilla’s reference web push server, or one of the several relays developed by the Mastodon community specifically for this purpose:

  • toot-relay
  • PushToFCM
  • metatext-apns

Subscribe to push notifications

POST /api/v1/push/subscription HTTP/1.1

Add a Web Push API subscription to receive notifications. Each access token can have one push subscription. If you create a new subscription, the old subscription is deleted.

Returns: WebPushSubscription
OAuth: User token + push
Version history:
2.4.0 - added
3.3.0 - added data[alerts][status]
3.4.0 - added data[policy]
3.5.0 - added data[alerts][update] and data[alerts][admin.sign_up]
4.0.0 - added data[alerts][admin.report]
4.3.0 - added stricter request parameter validation, invalid endpoint URLs and subscription keys will now result in an error, previously these would be accepted, but silently fail.
4.4.0 - added subscription[standard]

Request

Headers
Authorization
required Provide this header with Bearer <user_token> to gain authorized access to this API method.
Form data parameters
subscription[endpoint]
required String. The endpoint URL that is called when a notification event occurs.
subscription[keys][p256dh]
required String. User agent public key. Base64 encoded string of a public key from a ECDH keypair using the prime256v1 curve.
subscription[keys][auth]
required String. Auth secret. Base64 encoded string of 16 bytes of random data.
subscription[standard]
Boolean. Follow standardized webpush (RFC8030+RFC8291+RFC8292) ? Else follow legacy webpush (unpublished version, 4th draft of RFC8291 and 1st draft of RFC8292). Defaults to false.
data[alerts][mention]
Boolean. Receive mention notifications? Defaults to false.
data[alerts][status]
Boolean. Receive new subscribed account notifications? Defaults to false.
data[alerts][reblog]
Boolean. Receive reblog notifications? Defaults to false.
data[alerts][follow]
Boolean. Receive follow notifications? Defaults to false.
data[alerts][follow_request]
Boolean. Receive follow request notifications? Defaults to false.
data[alerts][favourite]
Boolean. Receive favourite notifications? Defaults to false.
data[alerts][poll]
Boolean. Receive poll notifications? Defaults to false.
data[alerts][update]
Boolean. Receive status edited notifications? Defaults to false.
data[alerts][admin.sign_up]
Boolean. Receive new user signup notifications? Defaults to false. Must have a role with the appropriate permissions.
data[alerts][admin.report]
Boolean. Receive new report notifications? Defaults to false. Must have a role with the appropriate permissions.
data[policy]
String. Specify whether to receive push notifications from all, followed, follower, or none users.

Response

200: OK

A new PushSubscription has been generated, which will send the requested alerts to your endpoint.

{
  "id": 328183,
  "endpoint": "https://yourdomain.example/listener",
  "standard": true,
  "alerts": {
    "follow": true,
    "favourite": true,
    "reblog": true,
    "mention": true,
    "poll": true
  },
  "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

Get current subscription

GET /api/v1/push/subscription HTTP/1.1

View the PushSubscription currently associated with this access token.

Returns: WebPushSubscription
OAuth: User token + push
Version history:
2.4.0 - added

Request

Headers
Authorization
required Provide this header with Bearer <user_token> to gain authorized access to this API method.

Response

200: OK
{
  "id": 328183,
  "endpoint": "https://yourdomain.example/listener",
  "standard": true,
  "alerts": {
    "follow": true,
    "favourite": true,
    "reblog": true,
    "mention": true,
    "poll": true
  },
  "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

A PushSubscription does not exist for this token.

{
  "error": "Record not found"
}

Change types of notifications

PUT /api/v1/push/subscription HTTP/1.1

Updates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead.

Returns: WebPushSubscription
OAuth: User token + push
Version history:
2.4.0 - added
3.3.0 - added data[alerts][status]
3.4.0 - added policy
3.5.0 - added data[alerts][update] and data[alerts][admin.sign_up]
4.0.0 - added data[alerts][admin.report]

Request

Headers
Authorization
required Provide this header with Bearer <user_token> to gain authorized access to this API method.
Form data parameters
data[alerts][mention]
Boolean. Receive mention notifications? Defaults to false.
data[alerts][status]
Boolean. Receive new subscribed account notifications? Defaults to false.
data[alerts][reblog]
Boolean. Receive reblog notifications? Defaults to false.
data[alerts][follow]
Boolean. Receive follow notifications? Defaults to false.
data[alerts][follow_request]
Boolean. Receive follow request notifications? Defaults to false.
data[alerts][favourite]
Boolean. Receive favourite notifications? Defaults to false.
data[alerts][poll]
Boolean. Receive poll notifications? Defaults to false.
data[alerts][update]
Boolean. Receive status edited notifications? Defaults to false.
data[alerts][admin.sign_up]
Boolean. Receive new user signup notifications? Defaults to false. Must have a role with the appropriate permissions.
data[alerts][admin.report]
Boolean. Receive new report notifications? Defaults to false. Must have a role with the appropriate permissions.
policy
String. Specify whether to receive push notifications from all, followed, follower, or none users.

Response

200: OK

Updating a PushSubscription to only receive mention alerts

{
  "id": 328183,
  "endpoint": "https://yourdomain.example/listener",
  "standard": true,
  "alerts": {
    "follow": false,
    "favourite": false,
    "reblog": false,
    "mention": true,
    "poll": false
  },
  "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

No existing PushSubscription for this token

{
  "error": "Record not found"
}

Remove current subscription

DELETE /api/v1/push/subscription HTTP/1.1

Removes the current Web Push API subscription.

Returns: Empty
OAuth: User token + push
Version history:
2.4.0 - added

Request

Headers
Authorization
required Provide this header with Bearer <user_token> to gain authorized access to this API method.

Response

200: OK

PushSubscription successfully deleted or did not exist previously

{}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

See also

app/controllers/api/v1/push/subscriptions_controller.rb

Last updated March 5, 2025 · Improve this page

Sponsored by

Dotcom-Monitor LoadView Stephen Tures Swayable SponsorMotion

Join Mastodon · Blog ·

View source · CC BY-SA 4.0 · Imprint