openapi: 3.0.3
info:
  title: Bluesky Application API (app.bsky)
  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
externalDocs:
  description: Bluesky HTTP API Reference
  url: https://docs.bsky.app/docs/advanced-guides/atproto
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: actor
    description: Actor (user) profile, search, and preference operations
  - name: feed
    description: Feed, post, timeline, and content operations
  - name: graph
    description: Graph operations — follows, blocks, lists, and mutes
  - name: notification
    description: Notification management
  - name: video
    description: Video upload and processing
  - name: labeler
    description: Labeling service operations
paths:
  /app.bsky.actor.getProfile:
    get:
      operationId: app_bsky_actor_getProfile
      summary: Get Profile
      description: >-
        Get detailed profile view of an actor. Does not require auth, but
        contains relevant metadata with auth.
      tags:
        - actor
      security:
        - {}
        - bearerAuth: []
      parameters:
        - name: actor
          in: query
          required: true
          description: Handle or DID of account to fetch profile of.
          schema:
            type: string
      responses:
        '200':
          description: Profile view
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileViewDetailed'
        '400':
          $ref: '#/components/responses/BadRequest'

  /app.bsky.actor.getProfiles:
    get:
      operationId: app_bsky_actor_getProfiles
      summary: Get Profiles
      description: Get detailed profile views of multiple actors.
      tags:
        - actor
      security:
        - {}
        - bearerAuth: []
      parameters:
        - name: actors
          in: query
          required: true
          description: List of handles or DIDs to fetch profiles of. Maximum 25.
          schema:
            type: array
            items:
              type: string
            maxItems: 25
          style: form
          explode: true
      responses:
        '200':
          description: Profile views
          content:
            application/json:
              schema:
                type: object
                required:
                  - profiles
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProfileViewDetailed'
        '400':
          $ref: '#/components/responses/BadRequest'

  /app.bsky.actor.searchActors:
    get:
      operationId: app_bsky_actor_searchActors
      summary: Search Actors
      description: Find actors (profiles) matching search criteria. Does not require auth.
      tags:
        - actor
      security:
        - {}
        - bearerAuth: []
      parameters:
        - name: q
          in: query
          required: false
          description: Search query string. Syntax, operators, and ranking of results subject to change.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: cursor
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Matching actors
          content:
            application/json:
              schema:
                type: object
                required:
                  - actors
                properties:
                  cursor:
                    type: string
                  actors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProfileView'
        '400':
          $ref: '#/components/responses/BadRequest'

  /app.bsky.actor.getPreferences:
    get:
      operationId: app_bsky_actor_getPreferences
      summary: Get Preferences
      description: Get private preferences attached to the current account.
      tags:
        - actor
      responses:
        '200':
          description: User preferences
          content:
            application/json:
              schema:
                type: object
                required:
                  - preferences
                properties:
                  preferences:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /app.bsky.actor.putPreferences:
    post:
      operationId: app_bsky_actor_putPreferences
      summary: Put Preferences
      description: Set the private preferences attached to the account.
      tags:
        - actor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - preferences
              properties:
                preferences:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
      responses:
        '200':
          description: Preferences updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /app.bsky.actor.getSuggestions:
    get:
      operationId: app_bsky_actor_getSuggestions
      summary: Get Suggestions
      description: Get a list of suggested actors (tending toward familiarity).
      tags:
        - actor
      security:
        - {}
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Suggested actors
          content:
            application/json:
              schema:
                type: object
                required:
                  - actors
                properties:
                  cursor:
                    type: string
                  actors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProfileView'

  /app.bsky.feed.getTimeline:
    get:
      operationId: app_bsky_feed_getTimeline
      summary: Get Timeline
      description: >-
        Get a view of the requesting account's home timeline. This is expected
        to be some form of reverse-chronological feed.
      tags:
        - feed
      parameters:
        - name: algorithm
          in: query
          required: false
          description: Variant algorithm for timeline. Implementation-specific.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Timeline feed
          content:
            application/json:
              schema:
                type: object
                required:
                  - feed
                properties:
                  cursor:
                    type: string
                  feed:
                    type: array
                    items:
                      $ref: '#/components/schemas/FeedViewPost'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /app.bsky.feed.getAuthorFeed:
    get:
      operationId: app_bsky_feed_getAuthorFeed
      summary: Get Author Feed
      description: Get a view of an actor's 'author feed' (a.k.a. profile feed). Does not require auth.
      tags:
        - feed
      security:
        - {}
        - bearerAuth: []
      parameters:
        - name: actor
          in: query
          required: true
          description: Handle or DID of account to fetch feed of.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          required: false
          schema:
            type: string
        - name: filter
          in: query
          required: false
          description: Combinations of post/repost types to include in response.
          schema:
            type: string
            enum:
              - posts_with_replies
              - posts_no_replies
              - posts_with_media
              - posts_and_author_threads
            default: posts_with_replies
        - name: includePins
          in: query
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: Author feed
          content:
            application/json:
              schema:
                type: object
                required:
                  - feed
                properties:
                  cursor:
                    type: string
                  feed:
                    type: array
                    items:
                      $ref: '#/components/schemas/FeedViewPost'
        '400':
          $ref: '#/components/responses/BadRequest'

  /app.bsky.feed.getPosts:
    get:
      operationId: app_bsky_feed_getPosts
      summary: Get Posts
      description: Gets post views for a specified list of posts (by AT-URI). Does not require auth.
      tags:
        - feed
      security:
        - {}
        - bearerAuth: []
      parameters:
        - name: uris
          in: query
          required: true
          description: List of post AT-URIs to fetch. Maximum 25.
          schema:
            type: array
            items:
              type: string
            maxItems: 25
          style: form
          explode: true
      responses:
        '200':
          description: Post views
          content:
            application/json:
              schema:
                type: object
                required:
                  - posts
                properties:
                  posts:
                    type: array
                    items:
                      $ref: '#/components/schemas/PostView'
        '400':
          $ref: '#/components/responses/BadRequest'

  /app.bsky.feed.getPostThread:
    get:
      operationId: app_bsky_feed_getPostThread
      summary: Get Post Thread
      description: Get posts in a thread. Does not require auth, but additional metadata and filtering will be applied for authed requests.
      tags:
        - feed
      security:
        - {}
        - bearerAuth: []
      parameters:
        - name: uri
          in: query
          required: true
          description: Reference (AT-URI) to post record.
          schema:
            type: string
        - name: depth
          in: query
          required: false
          description: How many levels of reply depth should be included in response.
          schema:
            type: integer
            minimum: 0
            maximum: 1000
            default: 6
        - name: parentHeight
          in: query
          required: false
          description: How many levels of parent (and grandparent, etc) post to include.
          schema:
            type: integer
            minimum: 0
            maximum: 1000
            default: 80
      responses:
        '200':
          description: Thread view
          content:
            application/json:
              schema:
                type: object
                required:
                  - thread
                properties:
                  thread:
                    type: object
                    description: ThreadViewPost or NotFoundPost or BlockedPost
                    additionalProperties: true
                  threadgate:
                    type: object
                    additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'

  /app.bsky.feed.searchPosts:
    get:
      operationId: app_bsky_feed_searchPosts
      summary: Search Posts
      description: Find posts matching search criteria, returning views of those posts.
      tags:
        - feed
      security:
        - {}
        - bearerAuth: []
      parameters:
        - name: q
          in: query
          required: true
          description: Search query string; syntax, operators, and ranking of results subject to change.
          schema:
            type: string
        - name: sort
          in: query
          required: false
          schema:
            type: string
            enum:
              - top
              - latest
            default: latest
        - name: since
          in: query
          required: false
          description: Filter results for posts after the indicated datetime (inclusive). Expected to use 'sortAt' timestamp, which may not match 'createdAt'.
          schema:
            type: string
            format: date-time
        - name: until
          in: query
          required: false
          description: Filter results for posts before the indicated datetime (not inclusive).
          schema:
            type: string
            format: date-time
        - name: mentions
          in: query
          required: false
          description: Filter to posts which mention the given account. Handles are resolved to DID before query. Only matches rich-text facet mentions.
          schema:
            type: string
        - name: author
          in: query
          required: false
          description: Filter to posts by the given account.
          schema:
            type: string
        - name: lang
          in: query
          required: false
          description: Filter to posts in the given language.
          schema:
            type: string
        - name: tag
          in: query
          required: false
          description: Filter to posts with the given tag (hashtag), based on rich-text facet or tag field. Do not include the '#' prefix.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: cursor
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Matching posts
          content:
            application/json:
              schema:
                type: object
                required:
                  - posts
                properties:
                  cursor:
                    type: string
                  hitsTotal:
                    type: integer
                    description: Count of search hits. Optional, may be rounded/truncated, and may not be possible to paginate through all hits.
                  posts:
                    type: array
                    items:
                      $ref: '#/components/schemas/PostView'
        '400':
          $ref: '#/components/responses/BadRequest'

  /app.bsky.feed.getLikes:
    get:
      operationId: app_bsky_feed_getLikes
      summary: Get Likes
      description: Get like records which reference a subject (by AT-URI with optional CID).
      tags:
        - feed
      security:
        - {}
        - bearerAuth: []
      parameters:
        - name: uri
          in: query
          required: true
          description: AT-URI of the subject (eg, a post record).
          schema:
            type: string
        - name: cid
          in: query
          required: false
          description: CID of the subject record (optional, to align with a specific version of the record).
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Like records
          content:
            application/json:
              schema:
                type: object
                required:
                  - uri
                  - likes
                properties:
                  uri:
                    type: string
                  cid:
                    type: string
                  cursor:
                    type: string
                  likes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Like'
        '400':
          $ref: '#/components/responses/BadRequest'

  /app.bsky.graph.getFollowers:
    get:
      operationId: app_bsky_graph_getFollowers
      summary: Get Followers
      description: Enumerates accounts which follow a specified account (actor).
      tags:
        - graph
      security:
        - {}
        - bearerAuth: []
      parameters:
        - name: actor
          in: query
          required: true
          description: Handle or DID of account to fetch followers of.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Followers list
          content:
            application/json:
              schema:
                type: object
                required:
                  - subject
                  - followers
                properties:
                  cursor:
                    type: string
                  subject:
                    $ref: '#/components/schemas/ProfileView'
                  followers:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProfileView'
        '400':
          $ref: '#/components/responses/BadRequest'

  /app.bsky.graph.getFollows:
    get:
      operationId: app_bsky_graph_getFollows
      summary: Get Follows
      description: Enumerates accounts which a specified account (actor) follows.
      tags:
        - graph
      security:
        - {}
        - bearerAuth: []
      parameters:
        - name: actor
          in: query
          required: true
          description: Handle or DID of account to fetch follows of.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Follows list
          content:
            application/json:
              schema:
                type: object
                required:
                  - subject
                  - follows
                properties:
                  cursor:
                    type: string
                  subject:
                    $ref: '#/components/schemas/ProfileView'
                  follows:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProfileView'
        '400':
          $ref: '#/components/responses/BadRequest'

  /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:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access JWT obtained from com.atproto.server.createSession

  responses:
    BadRequest:
      description: Bad request or validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
        message:
          type: string

    ProfileViewDetailed:
      type: object
      required:
        - did
        - handle
      properties:
        did:
          type: string
          description: Decentralized Identifier
        handle:
          type: string
          description: User handle (e.g., user.bsky.social)
        displayName:
          type: string
          maxLength: 640
        description:
          type: string
          maxLength: 2560
        avatar:
          type: string
          format: uri
        banner:
          type: string
          format: uri
        followersCount:
          type: integer
        followsCount:
          type: integer
        postsCount:
          type: integer
        associated:
          type: object
          description: Associated account data (lists, feeds, labeler, etc.)
          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'

    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'

    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

    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

    PostView:
      type: object
      required:
        - uri
        - cid
        - author
        - record
        - indexedAt
      properties:
        uri:
          type: string
          description: AT-URI of the post
        cid:
          type: string
        author:
          $ref: '#/components/schemas/ProfileView'
        record:
          type: object
          description: The post record
          additionalProperties: true
        embed:
          type: object
          description: Embedded content (images, external links, etc.)
          additionalProperties: true
        replyCount:
          type: integer
        repostCount:
          type: integer
        likeCount:
          type: integer
        quoteCount:
          type: integer
        indexedAt:
          type: string
          format: date-time
        viewer:
          type: object
          description: Viewer relationship to this post
          additionalProperties: true
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
        threadgate:
          type: object
          additionalProperties: true

    FeedViewPost:
      type: object
      required:
        - post
      properties:
        post:
          $ref: '#/components/schemas/PostView'
        reply:
          type: object
          description: Reply threading information
          properties:
            root:
              type: object
              additionalProperties: true
            parent:
              type: object
              additionalProperties: true
            grandparentAuthor:
              $ref: '#/components/schemas/ProfileView'
        reason:
          type: object
          description: Reason for appearing in feed (repost, pin, etc.)
          additionalProperties: true
        feedContext:
          type: string
          description: Context provided by feed generator

    Like:
      type: object
      required:
        - indexedAt
        - createdAt
        - actor
      properties:
        indexedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        actor:
          $ref: '#/components/schemas/ProfileView'

    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'