# OSF Notification Subscriptions API

**Canonical:** https://apis.io/apis/osf/osf-notification-subscriptions-api/  
**Provider:** OSF — https://apis.io/providers/osf/  
**Base URL:** https://api.osf.io  
**Documentation:** https://developer.osf.io

OSF Notification Subscriptions API is one of 41 APIs that [OSF](https://apis.io/providers/osf/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include Notification Subscriptions. The published artifact set on APIs.io includes an OpenAPI specification.

**Notification Subscriptions** allow users to manage how they receive alerts about activities and events related to OSF resources, such as projects, preprints, registrations, and collections. Subscriptions control **when** notifications are sent and **which events** trigger them. These subscriptions are **private** and are only visible to the authenticated user who owns them. ### Subscription Scope and Types Subscriptions can be configured at different scopes depending on the resource type: - **Global Subscriptions** Apply OSF-wide, affecting events like comment replies, mentions, and review updates across all resources. - **Node Subscriptions** Apply to individual projects or components (nodes), tracking events such as new comments or file updates. - **Provider Subscriptions** Apply to resources within a specific provider (collection, preprint, or registration providers). These subscriptions typically track events relevant to moderation workflows, such as new pending submissions. ### Attributes - `event_name` The specific event that triggers this subscription. Available event names depend on the scope of the subscription. Examples include: - `comments` - `file_updated` - `global_mentions` - `new_pending_submissions` - `frequency` Determines how often the user receives notifications for the event: - `instant`: Sends an email notification immediately after the event occurs. - `daily`: Groups event notifications into a daily summary email. - `none`: Disables notifications for the event. Users can update their notification frequency for each subscription. ### Relationships - `user` The user who owns the subscription. Each subscription is tied to a single user. - `provider` The provider associated with the subscription, if applicable. This may be a Collection Provider, Preprint Provider, or Registration Provider. Global subscriptions do not have a provider relationship. ### Available Event Names by Subscription Scope #### Node-Level Subscriptions Subscriptions specific to individual projects or components: - `comments`: Notify when comments are added. - `file_updated`: Notify when files are updated. #### Global Subscriptions Default notification preferences applied OSF-wide: - `global_comment_replies`: Notify when someone replies to your comments. - `global_comments`: Notify when comments are added to your projects. - `global_file_updated`: Notify when files are updated in your projects. - `global_mentions`: Notify when you are mentioned. - `global_reviews`: Notify when your preprint submissions are updated. #### Provider-Level Subscriptions Notifications related to moderation workflows or submissions within a specific provider: - `new_pending_submissions`: Notify when new preprint submissions are awaiting moderation. ### Notification Channels Notifications are delivered via **email**, according to the selected `frequency`: - `instant`: Immediate email notifications per event. - `daily`: Batched email summary delivered daily. - `none`: No email notifications are sent. ### Permissions and Access - Only the authenticated user who owns a subscription can view or update it. - Subscriptions are managed via the OSF API and reflect the user's current notification preferences for supported events.

## Operations (16)

| Method | Path | Summary |
|---|---|---|
| GET | `/subscriptions/` | Retrieve a List of Notification Subscriptions |
| GET | `/subscriptions/{subscription_id}/` | Retrieve a Notification Subscription |
| PATCH | `/subscriptions/{subscription_id}/` | Update a Notification Subscription |
| GET | `/providers/collections/{provider_id}/subscriptions/` | List Notification Subscriptions for a Collection Provider |
| GET | `/providers/collections/{provider_id}/subscriptions/{subscription_id}/` | Retrieve a Collection Provider Notification Subscription |
| PATCH | `/providers/collections/{provider_id}/subscriptions/{subscription_id}/` | Update a Collection Provider Notification Subscription |
| GET | `/providers/preprints/{provider_id}/subscriptions/` | List Preprint Provider Subscriptions |
| GET | `/providers/preprints/{provider_id}/subscriptions/{subscription_id}/` | Retrieve a Preprint Provider Subscription |
| PATCH | `/providers/preprints/{provider_id}/subscriptions/{subscription_id}/` | Update a Preprint Provider Subscription |
| GET | `/providers/registrations/{provider_id}/subscriptions/` | List Registration Provider Subscriptions |
| GET | `/providers/registrations/{provider_id}/subscriptions/{subscription_id}/` | Retrieve a Registration Provider Notification Subscription |
| PATCH | `/providers/registrations/{provider_id}/subscriptions/{subscription_id}/` | Update a Registration Provider Notification Subscription |
| GET | `/registration_subscriptions/{subscription_id}/` | Retrieve a Registration Provider Subscription |
| PATCH | `/registration_subscriptions/{subscription_id}/` | Update a Registration Provider Subscription |
| GET | `/collection_subscriptions/{subscription_id}/` | Retrieve a Collection Subscription |
| PATCH | `/collection_subscriptions/{subscription_id}/` | Update a Collection Subscription |

## Machine-readable artifacts (1)

- **OpenAPI** — https://artifacts.apis.io/osf/openapi/osf-notification-subscriptions-api-openapi.yml

## Other OSF APIs (12)

- [OSF API](https://apis.io/apis/osf/osf-api/)
- [OSF Actions API](https://apis.io/apis/osf/osf-actions-api/)
- [OSF Applications API](https://apis.io/apis/osf/osf-applications-api/)
- [OSF Base API](https://apis.io/apis/osf/osf-base-api/)
- [OSF CEDAR Metadata API](https://apis.io/apis/osf/osf-cedar-metadata-api/)
- [OSF Citations API](https://apis.io/apis/osf/osf-citations-api/)
- [OSF Collection Providers API](https://apis.io/apis/osf/osf-collection-providers-api/)
- [OSF Collection Submission Actions API](https://apis.io/apis/osf/osf-collection-submission-actions-api/)
- [OSF Collection Submissions API](https://apis.io/apis/osf/osf-collection-submissions-api/)
- [OSF Collections API](https://apis.io/apis/osf/osf-collections-api/)
- [OSF Comments API](https://apis.io/apis/osf/osf-comments-api/)
- [OSF Contributors API](https://apis.io/apis/osf/osf-contributors-api/)

## Tags

Notification Subscriptions

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/osf/osf-notification-subscriptions-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/osf/.