Bluesky
Bluesky Notifications API

Operations for managing user notifications.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  title: Bluesky Social Actor Profiles Notifications API
  description: "The Bluesky Social API provides programmatic access to the Bluesky social network built on the AT Protocol. \n\nThis API enables developers to:\n- Manage user profiles and preferences\n- Create, read, and interact with posts and feeds\n- Handle social graph operations (follows, blocks, mutes)\n- Process notifications and conversations\n- Moderate content and manage labels\n- Synchronize repository data\n\nAuthentication is handled via Bearer tokens. Public endpoints can be accessed directly at https://public.api.bsky.app, while authenticated requests should be made to the user's Personal Data Server (PDS).\n\nFor more information, visit the [Bluesky API Documentation](https://docs.bsky.app)."
  version: 1.0.0
  contact:
    name: Bluesky Support
    url: https://bsky.app
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://bsky.social/xrpc
  description: Bluesky Social PDS
- url: https://public.api.bsky.app/xrpc
  description: Public Bluesky AppView API (unauthenticated endpoints)
tags:
- name: Notifications
  description: Operations for managing user notifications.
paths:
  /xrpc/app.bsky.notification.getUnreadCount:
    get:
      operationId: notificationGetUnreadCount
      summary: Bluesky Count the number of unread notifications for the requesting account.
      description: '*This endpoint is part of the Bluesky application Lexicon APIs (`app.bsky.*`). Public endpoints which don''t require authentication can be made directly against the public Bluesky AppView API: https://public.api.bsky.app. Authenticated requests are usually made to the user''s PDS, with automatic service proxying. Authenticated requests can be used for both public and non-public endpoints.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Count the number of unread notifications for the requesting account. Requires auth.'
      tags:
      - Notifications
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: priority
        in: query
        required: false
        schema:
          type: boolean
        example: true
      - name: seenAt
        in: query
        required: false
        schema:
          type: string
          format: date-time
        example: '2024-01-15T12:00:00.000Z'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - count
                properties:
                  count:
                    type: integer
              examples:
                NotificationGetUnreadCountResponse200Example:
                  $ref: '#/components/examples/NotificationGetUnreadCountResponse200Example'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/app.bsky.notification.listNotifications:
    get:
      operationId: notificationListNotifications
      summary: Bluesky Enumerate notifications for the requesting account.
      description: '*This endpoint is part of the Bluesky application Lexicon APIs (`app.bsky.*`). Public endpoints which don''t require authentication can be made directly against the public Bluesky AppView API: https://public.api.bsky.app. Authenticated requests are usually made to the user''s PDS, with automatic service proxying. Authenticated requests can be used for both public and non-public endpoints.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Enumerate notifications for the requesting account. Requires auth.'
      tags:
      - Notifications
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        example: 50
      - name: priority
        in: query
        required: false
        schema:
          type: boolean
        example: true
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      - name: seenAt
        in: query
        required: false
        schema:
          type: string
          format: date-time
        example: '2024-01-15T12:00:00.000Z'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - notifications
                properties:
                  cursor:
                    type: string
                  notifications:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppBskyNotificationListNotificationsNotification'
                  priority:
                    type: boolean
                  seenAt:
                    type: string
                    format: date-time
              examples:
                NotificationListNotificationsResponse200Example:
                  $ref: '#/components/examples/NotificationListNotificationsResponse200Example'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/app.bsky.notification.putPreferences:
    post:
      operationId: notificationPutPreferences
      summary: Bluesky Set notification-related preferences for an account.
      description: '*This endpoint is part of the Bluesky application Lexicon APIs (`app.bsky.*`). Public endpoints which don''t require authentication can be made directly against the public Bluesky AppView API: https://public.api.bsky.app. Authenticated requests are usually made to the user''s PDS, with automatic service proxying. Authenticated requests can be used for both public and non-public endpoints.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Set notification-related preferences for an account. Requires auth.'
      tags:
      - Notifications
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - priority
              properties:
                priority:
                  type: boolean
            examples:
              NotificationPutPreferencesRequestExample:
                $ref: '#/components/examples/NotificationPutPreferencesRequestExample'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/app.bsky.notification.registerPush:
    post:
      operationId: notificationRegisterPush
      summary: Bluesky Register to receive push notifications, via a specified service, for the requesting account.
      description: '*This endpoint is part of the Bluesky application Lexicon APIs (`app.bsky.*`). Public endpoints which don''t require authentication can be made directly against the public Bluesky AppView API: https://public.api.bsky.app. Authenticated requests are usually made to the user''s PDS, with automatic service proxying. Authenticated requests can be used for both public and non-public endpoints.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Register to receive push notifications, via a specified service, for the requesting account. Requires auth.'
      tags:
      - Notifications
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - serviceDid
              - token
              - platform
              - appId
              properties:
                serviceDid:
                  type: string
                  format: did
                token:
                  type: string
                platform:
                  type: string
                  enum:
                  - ios
                  - android
                  - web
                appId:
                  type: string
            examples:
              NotificationRegisterPushRequestExample:
                $ref: '#/components/examples/NotificationRegisterPushRequestExample'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/app.bsky.notification.updateSeen:
    post:
      operationId: notificationUpdateSeen
      summary: Bluesky Notify server that the requesting account has seen notifications.
      description: '*This endpoint is part of the Bluesky application Lexicon APIs (`app.bsky.*`). Public endpoints which don''t require authentication can be made directly against the public Bluesky AppView API: https://public.api.bsky.app. Authenticated requests are usually made to the user''s PDS, with automatic service proxying. Authenticated requests can be used for both public and non-public endpoints.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*


        Notify server that the requesting account has seen notifications. Requires auth.'
      tags:
      - Notifications
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - seenAt
              properties:
                seenAt:
                  type: string
                  format: date-time
            examples:
              NotificationUpdateSeenRequestExample:
                $ref: '#/components/examples/NotificationUpdateSeenRequestExample'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
components:
  schemas:
    AppBskyGraphDefsListViewBasic:
      type: object
      required:
      - uri
      - cid
      - name
      - purpose
      properties:
        uri:
          type: string
          format: at-uri
        cid:
          type: string
          format: cid
        name:
          type: string
          minLength: 1
          maxLength: 64
        purpose:
          $ref: '#/components/schemas/AppBskyGraphDefsListPurpose'
        avatar:
          type: string
          format: uri
        listItemCount:
          type: integer
          minimum: 0
        labels:
          type: array
          items:
            $ref: '#/components/schemas/ComAtprotoLabelDefsLabel'
        viewer:
          $ref: '#/components/schemas/AppBskyGraphDefsListViewerState'
        indexedAt:
          type: string
          format: date-time
    ComAtprotoLabelDefsLabel:
      type: object
      description: Metadata tag on an atproto resource (eg, repo or record).
      required:
      - src
      - uri
      - val
      - cts
      properties:
        ver:
          type: integer
        src:
          type: string
          description: DID of the actor who created this label.
          format: did
        uri:
          type: string
          description: AT URI of the record, repository (account), or other resource that this label applies to.
          format: uri
        cid:
          type: string
          description: Optionally, CID specifying the specific version of 'uri' resource this label applies to.
          format: cid
        val:
          type: string
          description: The short string name of the value or type of this label.
          maxLength: 128
        neg:
          type: boolean
          description: If true, this is a negation label, overwriting a previous label.
        cts:
          type: string
          description: Timestamp when this label was created.
          format: date-time
        exp:
          type: string
          description: Timestamp at which this label expires (no longer applies).
          format: date-time
        sig:
          type: string
          format: byte
          description: Signature of dag-cbor encoded label.
    AppBskyActorDefsProfileView:
      type: object
      required:
      - did
      - handle
      properties:
        did:
          type: string
          format: did
        handle:
          type: string
          format: handle
        displayName:
          type: string
          maxLength: 640
        description:
          type: string
          maxLength: 2560
        avatar:
          type: string
          format: uri
        associated:
          $ref: '#/components/schemas/AppBskyActorDefsProfileAssociated'
        indexedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        viewer:
          $ref: '#/components/schemas/AppBskyActorDefsViewerState'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/ComAtprotoLabelDefsLabel'
    AppBskyActorDefsProfileAssociatedChat:
      type: object
      required:
      - allowIncoming
      properties:
        allowIncoming:
          type: string
          enum:
          - all
          - none
          - following
    AppBskyActorDefsViewerState:
      type: object
      description: Metadata about the requesting account's relationship with the subject account. Only has meaningful content for authed requests.
      properties:
        muted:
          type: boolean
        mutedByList:
          $ref: '#/components/schemas/AppBskyGraphDefsListViewBasic'
        blockedBy:
          type: boolean
        blocking:
          type: string
          format: at-uri
        blockingByList:
          $ref: '#/components/schemas/AppBskyGraphDefsListViewBasic'
        following:
          type: string
          format: at-uri
        followedBy:
          type: string
          format: at-uri
        knownFollowers:
          $ref: '#/components/schemas/AppBskyActorDefsKnownFollowers'
    AppBskyNotificationListNotificationsNotification:
      type: object
      required:
      - uri
      - cid
      - author
      - reason
      - record
      - isRead
      - indexedAt
      properties:
        uri:
          type: string
          format: at-uri
        cid:
          type: string
          format: cid
        author:
          $ref: '#/components/schemas/AppBskyActorDefsProfileView'
        reason:
          type: string
          description: Expected values are 'like', 'repost', 'follow', 'mention', 'reply', 'quote', and 'starterpack-joined'.
          enum:
          - like
          - repost
          - follow
          - mention
          - reply
          - quote
          - starterpack-joined
        reasonSubject:
          type: string
          format: at-uri
        record: {}
        isRead:
          type: boolean
        indexedAt:
          type: string
          format: date-time
        labels:
          type: array
          items:
            $ref: '#/components/schemas/ComAtprotoLabelDefsLabel'
    AppBskyActorDefsProfileAssociated:
      type: object
      properties:
        lists:
          type: integer
        feedgens:
          type: integer
        starterPacks:
          type: integer
        labeler:
          type: boolean
        chat:
          $ref: '#/components/schemas/AppBskyActorDefsProfileAssociatedChat'
    AppBskyActorDefsKnownFollowers:
      type: object
      description: The subject's followers whom you also follow
      required:
      - count
      - followers
      properties:
        count:
          type: integer
        followers:
          type: array
          items:
            $ref: '#/components/schemas/AppBskyActorDefsProfileViewBasic'
          maxItems: 5
    AppBskyActorDefsProfileViewBasic:
      type: object
      required:
      - did
      - handle
      properties:
        did:
          type: string
          format: did
        handle:
          type: string
          format: handle
        displayName:
          type: string
          maxLength: 640
        avatar:
          type: string
          format: uri
        associated:
          $ref: '#/components/schemas/AppBskyActorDefsProfileAssociated'
        viewer:
          $ref: '#/components/schemas/AppBskyActorDefsViewerState'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/ComAtprotoLabelDefsLabel'
        createdAt:
          type: string
          format: date-time
    AppBskyGraphDefsListPurpose:
      oneOf:
      - $ref: '#/components/schemas/AppBskyGraphDefsModlist'
      - $ref: '#/components/schemas/AppBskyGraphDefsCuratelist'
      - $ref: '#/components/schemas/AppBskyGraphDefsReferencelist'
    AppBskyGraphDefsCuratelist:
      type: string
      format: token
      description: A list of actors used for curation purposes such as list feeds or interaction gating.
    AppBskyGraphDefsReferencelist:
      type: string
      format: token
      description: A list of actors used for only for reference purposes such as within a starter pack.
    AppBskyGraphDefsModlist:
      type: string
      format: token
      description: A list of actors to apply an aggregate moderation action (mute/block) on.
    AppBskyGraphDefsListViewerState:
      type: object
      properties:
        muted:
          type: boolean
        blocked:
          type: string
          format: at-uri
  examples:
    NotificationUpdateSeenRequestExample:
      summary: Example request for notificationUpdateSeen
      value:
        seenAt: '2024-01-15T12:00:00.000Z'
    NotificationListNotificationsResponse200Example:
      summary: Successful response for notificationListNotifications
      value:
        notifications:
        - uri: at://did:plc:example123/app.bsky.feed.post/abc123
          cid: bafyreiabc123example
          author:
            did: did:plc:example123abc
            handle: user.bsky.social
            displayName: Example Name
            description: This is an example description.
            avatar: https://example.com/resource
            associated: {}
            indexedAt: '2024-01-15T12:00:00.000Z'
            createdAt: '2024-01-15T12:00:00.000Z'
          reason: like
          record: {}
          isRead: true
          indexedAt: '2024-01-15T12:00:00.000Z'
          reasonSubject: at://did:plc:example123/app.bsky.feed.post/abc123
        cursor: eyJsYXN0SWQiOiIxMjM0NTYifQ
        priority: true
        seenAt: '2024-01-15T12:00:00.000Z'
    NotificationGetUnreadCountResponse200Example:
      summary: Successful response for notificationGetUnreadCount
      value:
        count: 50
    NotificationPutPreferencesRequestExample:
      summary: Example request for notificationPutPreferences
      value:
        priority: true
    NotificationRegisterPushRequestExample:
      summary: Example request for notificationRegisterPush
      value:
        serviceDid: did:plc:example123abc
        token: example-token
        platform: ios
        appId: example-appId
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
Bluesky Notifications API

Documentation

Specifications

Other Resources

OpenAPI Specification
