openapi: 3.0.3
info:
  title: Bluesky Application API (app.bsky) actor 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: actor
  description: Actor (user) profile, search, and preference 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'
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
    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'
    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'
  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