openapi: 3.0.3
info:
  title: Bluesky Application API (app.bsky) actor feed 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: feed
  description: Feed, post, timeline, and content operations
paths:
  /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'
components:
  schemas:
    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'
    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
    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
    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'
    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
  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