Bluesky Social Graph API

openapi: 3.1.0
info:
  title: Bluesky Social Actor Profiles Social Graph 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: Social Graph
  description: Operations for managing follows, followers, blocks, mutes, and lists.
paths:
  /xrpc/app.bsky.graph.getActorStarterPacks:
    get:
      operationId: graphGetActorStarterPacks
      summary: Bluesky Get a list of starter packs created by the actor.
      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.*


        Get a list of starter packs created by the actor.'
      tags:
      - Social Graph
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: actor
        in: query
        required: true
        schema:
          type: string
          format: at-identifier
        example: user.bsky.social
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        example: 50
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - starterPacks
                properties:
                  cursor:
                    type: string
                  starterPacks:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppBskyGraphDefsStarterPackViewBasic'
              examples:
                GraphGetActorStarterPacksResponse200Example:
                  $ref: '#/components/examples/GraphGetActorStarterPacksResponse200Example'
        '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.graph.getBlocks:
    get:
      operationId: graphGetBlocks
      summary: Bluesky Enumerates which accounts the requesting account is currently blocking.
      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.*


        Enumerates which accounts the requesting account is currently blocking. Requires auth.'
      tags:
      - Social Graph
      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: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - blocks
                properties:
                  cursor:
                    type: string
                  blocks:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppBskyActorDefsProfileView'
              examples:
                GraphGetBlocksResponse200Example:
                  $ref: '#/components/examples/GraphGetBlocksResponse200Example'
        '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.graph.getFollowers:
    get:
      operationId: graphGetFollowers
      summary: Bluesky Enumerates accounts which follow a specified account (actor).
      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.*


        Enumerates accounts which follow a specified account (actor).'
      tags:
      - Social Graph
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: actor
        in: query
        required: true
        schema:
          type: string
          format: at-identifier
        example: user.bsky.social
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        example: 50
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - subject
                - followers
                properties:
                  subject:
                    $ref: '#/components/schemas/AppBskyActorDefsProfileView'
                  cursor:
                    type: string
                  followers:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppBskyActorDefsProfileView'
              examples:
                GraphGetFollowersResponse200Example:
                  $ref: '#/components/examples/GraphGetFollowersResponse200Example'
        '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.graph.getFollows:
    get:
      operationId: graphGetFollows
      summary: Bluesky Enumerates accounts which a specified account (actor) follows.
      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.*


        Enumerates accounts which a specified account (actor) follows.'
      tags:
      - Social Graph
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: actor
        in: query
        required: true
        schema:
          type: string
          format: at-identifier
        example: user.bsky.social
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        example: 50
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - subject
                - follows
                properties:
                  subject:
                    $ref: '#/components/schemas/AppBskyActorDefsProfileView'
                  cursor:
                    type: string
                  follows:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppBskyActorDefsProfileView'
              examples:
                GraphGetFollowsResponse200Example:
                  $ref: '#/components/examples/GraphGetFollowsResponse200Example'
        '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.graph.getKnownFollowers:
    get:
      operationId: graphGetKnownFollowers
      summary: Bluesky Enumerates accounts which follow a specified account (actor) and are followed by the viewer.
      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.*


        Enumerates accounts which follow a specified account (actor) and are followed by the viewer.'
      tags:
      - Social Graph
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: actor
        in: query
        required: true
        schema:
          type: string
          format: at-identifier
        example: user.bsky.social
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        example: 50
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - subject
                - followers
                properties:
                  subject:
                    $ref: '#/components/schemas/AppBskyActorDefsProfileView'
                  cursor:
                    type: string
                  followers:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppBskyActorDefsProfileView'
              examples:
                GraphGetKnownFollowersResponse200Example:
                  $ref: '#/components/examples/GraphGetKnownFollowersResponse200Example'
        '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.graph.getList:
    get:
      operationId: graphGetList
      summary: Bluesky Gets a 'view' (with additional context) of a specified list.
      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.*


        Gets a ''view'' (with additional context) of a specified list.'
      tags:
      - Social Graph
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: list
        in: query
        description: Reference (AT-URI) of the list record to hydrate.
        required: true
        schema:
          type: string
          description: Reference (AT-URI) of the list record to hydrate.
          format: at-uri
        example: at://did:plc:example123/app.bsky.feed.post/abc123
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        example: 50
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - list
                - items
                properties:
                  cursor:
                    type: string
                  list:
                    $ref: '#/components/schemas/AppBskyGraphDefsListView'
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppBskyGraphDefsListItemView'
              examples:
                GraphGetListResponse200Example:
                  $ref: '#/components/examples/GraphGetListResponse200Example'
        '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.graph.getListBlocks:
    get:
      operationId: graphGetListBlocks
      summary: Bluesky Get mod lists that the requesting account (actor) is blocking.
      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.*


        Get mod lists that the requesting account (actor) is blocking. Requires auth.'
      tags:
      - Social Graph
      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: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - lists
                properties:
                  cursor:
                    type: string
                  lists:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppBskyGraphDefsListView'
              examples:
                GraphGetListBlocksResponse200Example:
                  $ref: '#/components/examples/GraphGetListBlocksResponse200Example'
        '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.graph.getListMutes:
    get:
      operationId: graphGetListMutes
      summary: Bluesky Enumerates mod lists that the requesting account (actor) currently has muted.
      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.*


        Enumerates mod lists that the requesting account (actor) currently has muted. Requires auth.'
      tags:
      - Social Graph
      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: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - lists
                properties:
                  cursor:
                    type: string
                  lists:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppBskyGraphDefsListView'
              examples:
                GraphGetListMutesResponse200Example:
                  $ref: '#/components/examples/GraphGetListMutesResponse200Example'
        '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.graph.getLists:
    get:
      operationId: graphGetLists
      summary: Bluesky Enumerates the lists created by a specified account (actor).
      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.*


        Enumerates the lists created by a specified account (actor).'
      tags:
      - Social Graph
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: actor
        in: query
        description: The account (actor) to enumerate lists from.
        required: true
        schema:
          type: string
          description: The account (actor) to enumerate lists from.
          format: at-identifier
        example: user.bsky.social
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        example: 50
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - lists
                properties:
                  cursor:
                    type: string
                  lists:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppBskyGraphDefsListView'
              examples:
                GraphGetListsResponse200Example:
                  $ref: '#/components/examples/GraphGetListsResponse200Example'
        '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.graph.getMutes:
    get:
      operationId: graphGetMutes
      summary: Bluesky Enumerates accounts that the requesting account (actor) currently has muted.
      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.*


        Enumerates accounts that the requesting account (actor) currently has muted. Requires auth.'
      tags:
      - Social Graph
      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: cursor
        in: query
        required: false
        schema:
          type: string
        example: eyJsYXN0SWQiOiIxMjM0NTYifQ
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - mutes
                properties:
                  cursor:
                    type: string
                  mutes:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppBskyActorDefsProfileView'
              examples:
                GraphGetMutesResponse200Example:
                  $ref: '#/components/examples/GraphGetMutesResponse200Example'
        '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.graph.getRelationships:
    get:
      operationId: graphGetRelationships
      summary: Bluesky Enumerates public relationships between one account, and a list of other accounts.
      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.*


        Enumerates public relationships between one account, and a list of other accounts. Does not require auth.'
      tags:
      - Social Graph
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: actor
        in: query
        description: Primary account requesting relationships for.
        required: true
 

# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bluesky/refs/heads/main/openapi/bluesky-social-graph-api-openapi.yml