openapi: 3.0.3
info:
  title: Bluesky Application API (app.bsky) actor notification API
  description: The Bluesky application-layer Lexicon API providing feed, actor, graph, notification, and video endpoints for the microblogging application built on AT Protocol. The AppView is accessible unauthenticated at public.api.bsky.app for read operations, and at api.bsky.app for authenticated write operations. Schemas are defined using Lexicon, AT Protocol's schema definition language.
  version: 1.0.0
  contact:
    name: Bluesky
    url: https://docs.bsky.app/
  license:
    name: MIT / Apache-2.0
    url: https://github.com/bluesky-social/atproto/blob/main/LICENSE.txt
servers:
- url: https://public.api.bsky.app/xrpc
  description: Public AppView (unauthenticated read operations)
- url: https://api.bsky.app/xrpc
  description: Authenticated AppView (write operations)
security:
- bearerAuth: []
- {}
tags:
- name: notification
  description: Notification management
paths:
  /app.bsky.notification.listNotifications:
    get:
      operationId: app_bsky_notification_listNotifications
      summary: List Notifications
      description: Enumerate notifications for the requesting account. Requires auth.
      tags:
      - notification
      parameters:
      - name: reasons
        in: query
        required: false
        description: Notification reasons to include in response.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: priority
        in: query
        required: false
        schema:
          type: boolean
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      - name: seenAt
        in: query
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Notifications
          content:
            application/json:
              schema:
                type: object
                required:
                - notifications
                properties:
                  cursor:
                    type: string
                  notifications:
                    type: array
                    items:
                      $ref: '#/components/schemas/Notification'
                  priority:
                    type: boolean
                  seenAt:
                    type: string
                    format: date-time
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /app.bsky.notification.getUnreadCount:
    get:
      operationId: app_bsky_notification_getUnreadCount
      summary: Get Unread Count
      description: Count the number of unread notifications for the requesting account. Requires auth.
      tags:
      - notification
      parameters:
      - name: priority
        in: query
        required: false
        schema:
          type: boolean
      - name: seenAt
        in: query
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Unread notification count
          content:
            application/json:
              schema:
                type: object
                required:
                - count
                properties:
                  count:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Label:
      type: object
      required:
      - src
      - uri
      - val
      - cts
      properties:
        ver:
          type: integer
        src:
          type: string
          description: DID of the actor who created this label
        uri:
          type: string
          description: AT URI of the record, repository (account), or other resource this label applies to
        cid:
          type: string
          description: Optionally constrains label to specific version of record/blob
        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
          format: date-time
          description: Timestamp when this label was created
        exp:
          type: string
          format: date-time
          description: Timestamp at which this label expires
    Error:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
        message:
          type: string
    ViewerState:
      type: object
      description: Metadata about the relationship between the requesting account and the subject account.
      properties:
        muted:
          type: boolean
        mutedByList:
          type: object
          additionalProperties: true
        blockedBy:
          type: boolean
        blocking:
          type: string
          description: AT-URI of the blocking record, if present
        blockingByList:
          type: object
          additionalProperties: true
        following:
          type: string
          description: AT-URI of the follow record, if present
        followedBy:
          type: string
          description: AT-URI of the follow record from the subject to the requester
        knownFollowers:
          type: object
          additionalProperties: true
    Notification:
      type: object
      required:
      - uri
      - cid
      - author
      - reason
      - record
      - isRead
      - indexedAt
      properties:
        uri:
          type: string
          description: AT-URI of the notification record
        cid:
          type: string
        author:
          $ref: '#/components/schemas/ProfileView'
        reason:
          type: string
          description: Expected values are 'like', 'repost', 'follow', 'mention', 'reply', 'quote', 'starterpack-joined'
          enum:
          - like
          - repost
          - follow
          - mention
          - reply
          - quote
          - starterpack-joined
        reasonSubject:
          type: string
          description: AT-URI of the record that is the subject of the notification
        record:
          type: object
          additionalProperties: true
        isRead:
          type: boolean
        indexedAt:
          type: string
          format: date-time
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
    ProfileView:
      type: object
      required:
      - did
      - handle
      properties:
        did:
          type: string
        handle:
          type: string
        displayName:
          type: string
        description:
          type: string
        avatar:
          type: string
          format: uri
        associated:
          type: object
          additionalProperties: true
        indexedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        viewer:
          $ref: '#/components/schemas/ViewerState'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request or validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access JWT obtained from com.atproto.server.createSession
externalDocs:
  description: Bluesky HTTP API Reference
  url: https://docs.bsky.app/docs/advanced-guides/atproto