openapi: 3.1.0
info:
title: Bluesky Social 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: Actor Profiles
description: Operations for managing user profiles, preferences, and actor information.
- name: Administration
description: Administrative operations for managing accounts and invites.
- name: Chat Actors
description: Operations for managing chat actor settings and declarations.
- name: Chat Moderation
description: Operations for moderating chat content.
- name: Content Labels
description: Operations for managing content labelers and label subscriptions.
- name: Conversations
description: Operations for managing direct message conversations.
- name: Feeds
description: Operations for managing feeds, posts, likes, and reposts.
- name: Identity
description: Operations for identity management and DID resolution.
- name: Labels
description: Operations for content labeling and moderation.
- name: Moderation
description: Operations for content moderation reporting.
- name: Notifications
description: Operations for managing user notifications.
- name: Ozone Communication
description: Ozone moderation tool communication operations.
- name: Ozone Moderation
description: Ozone moderation tool operations.
- name: Ozone Server
description: Ozone server configuration operations.
- name: Ozone Sets
description: Ozone set management operations.
- name: Ozone Settings
description: Ozone settings management operations.
- name: Ozone Signatures
description: Ozone signature and threat analysis operations.
- name: Ozone Team
description: Ozone team member management operations.
- name: Repository
description: Operations for managing AT Protocol repositories.
- name: Server
description: Operations for server management and authentication.
- name: Social Graph
description: Operations for managing follows, followers, blocks, mutes, and lists.
- name: Sync
description: Operations for repository synchronization.
- name: Video
description: Operations for video upload and processing.
paths:
/xrpc/app.bsky.actor.getPreferences:
get:
operationId: actorGetPreferences
summary: Bluesky Get private preferences attached to the current account.
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 private preferences attached to the current account. Expected use is synchronization between multiple devices, and import/export during account migration. Requires auth.
tags:
- Actor Profiles
x-microcks-operation:
delay: 100
dispatcher: FALLBACK
dispatcherRules: ''
security:
- Bearer: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- preferences
properties:
preferences:
$ref: '#/components/schemas/AppBskyActorDefsPreferences'
examples:
ActorGetPreferencesResponse200Example:
$ref: '#/components/examples/ActorGetPreferencesResponse200Example'
'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.actor.getProfile:
get:
operationId: actorGetProfile
summary: Bluesky Get detailed profile view of an 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 detailed profile view of an actor. Does not require auth, but contains relevant metadata with auth.
tags:
- Actor Profiles
x-microcks-operation:
delay: 100
dispatcher: FALLBACK
dispatcherRules: ''
security:
- Bearer: []
parameters:
- name: actor
in: query
description: Handle or DID of account to fetch profile of.
required: true
schema:
type: string
description: Handle or DID of account to fetch profile of.
format: at-identifier
example: user.bsky.social
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AppBskyActorDefsProfileViewDetailed'
examples:
ActorGetProfileResponse200Example:
$ref: '#/components/examples/ActorGetProfileResponse200Example'
'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.actor.getProfiles:
get:
operationId: actorGetProfiles
summary: Bluesky Get detailed profile views of multiple actors.
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 detailed profile views of multiple actors.
tags:
- Actor Profiles
x-microcks-operation:
delay: 100
dispatcher: FALLBACK
dispatcherRules: ''
security:
- Bearer: []
parameters:
- name: actors
in: query
required: true
schema:
type: array
items:
type: string
format: at-identifier
maxItems: 25
example:
- user.bsky.social
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- profiles
properties:
profiles:
type: array
items:
$ref: '#/components/schemas/AppBskyActorDefsProfileViewDetailed'
examples:
ActorGetProfilesResponse200Example:
$ref: '#/components/examples/ActorGetProfilesResponse200Example'
'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.actor.getSuggestions:
get:
operationId: actorGetSuggestions
summary: Bluesky Get a list of suggested actors.
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 suggested actors. Expected use is discovery of accounts to follow during new account onboarding.
tags:
- Actor Profiles
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:
- actors
properties:
cursor:
type: string
actors:
type: array
items:
$ref: '#/components/schemas/AppBskyActorDefsProfileView'
examples:
ActorGetSuggestionsResponse200Example:
$ref: '#/components/examples/ActorGetSuggestionsResponse200Example'
'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.actor.putPreferences:
post:
operationId: actorPutPreferences
summary: Bluesky Set the private preferences attached to the account.
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.*
Set the private preferences attached to the account.
tags:
- Actor Profiles
x-microcks-operation:
delay: 100
dispatcher: FALLBACK
dispatcherRules: ''
security:
- Bearer: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- preferences
properties:
preferences:
$ref: '#/components/schemas/AppBskyActorDefsPreferences'
examples:
ActorPutPreferencesRequestExample:
$ref: '#/components/examples/ActorPutPreferencesRequestExample'
responses:
'200':
description: OK
'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.actor.searchActors:
get:
operationId: actorSearchActors
summary: Bluesky Find actors (profiles) matching search criteria.
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.*
Find actors (profiles) matching search criteria. Does not require auth.
tags:
- Actor Profiles
x-microcks-operation:
delay: 100
dispatcher: FALLBACK
dispatcherRules: ''
security:
- Bearer: []
parameters:
- name: q
in: query
description: Search query string. Syntax, phrase, boolean, and faceting is unspecified, but Lucene query syntax is recommended.
required: false
schema:
type: string
description: Search query string. Syntax, phrase, boolean, and faceting is unspecified, but Lucene query syntax is recommended.
example: example-q
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 25
example: 25
- name: cursor
in: query
required: false
schema:
type: string
example: eyJsYXN0SWQiOiIxMjM0NTYifQ
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- actors
properties:
cursor:
type: string
actors:
type: array
items:
$ref: '#/components/schemas/AppBskyActorDefsProfileView'
examples:
ActorSearchActorsResponse200Example:
$ref: '#/components/examples/ActorSearchActorsResponse200Example'
'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.actor.searchActorsTypeahead:
get:
operationId: actorSearchActorsTypeahead
summary: Bluesky Find actor suggestions for a prefix search term.
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.*
Find actor suggestions for a prefix search term. Expected use is for auto-completion during text field entry. Does not require auth.
tags:
- Actor Profiles
x-microcks-operation:
delay: 100
dispatcher: FALLBACK
dispatcherRules: ''
security:
- Bearer: []
parameters:
- name: q
in: query
description: Search query prefix; not a full query string.
required: false
schema:
type: string
description: Search query prefix; not a full query string.
example: example-q
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 10
example: 10
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- actors
properties:
actors:
type: array
items:
$ref: '#/components/schemas/AppBskyActorDefsProfileViewBasic'
examples:
ActorSearchActorsTypeaheadResponse200Example:
$ref: '#/components/examples/ActorSearchActorsTypeaheadResponse200Example'
'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.feed.describeFeedGenerator:
get:
operationId: feedDescribeFeedGenerator
summary: Bluesky Get information about a feed generator, including policies and offered feed URIs.
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 information about a feed generator, including policies and offered feed URIs. Does not require auth; implemented by Feed Generator services (not App View).
tags:
- Feeds
x-microcks-operation:
delay: 100
dispatcher: FALLBACK
dispatcherRules: ''
security:
- Bearer: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- did
- feeds
properties:
did:
type: string
format: did
feeds:
type: array
items:
$ref: '#/components/schemas/AppBskyFeedDescribeFeedGeneratorFeed'
links:
$ref: '#/components/schemas/AppBskyFeedDescribeFeedGeneratorLinks'
examples:
FeedDescribeFeedGeneratorResponse200Example:
$ref: '#/components/examples/FeedDescribeFeedGeneratorResponse200Example'
'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.feed.getActorFeeds:
get:
operationId: feedGetActorFeeds
summary: Bluesky Get a list of feeds (feed generator records) created by the actor (in the actor's repo).
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 feeds (feed generator records) created by the actor (in the actor's repo).
tags:
- Feeds
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:
- feeds
properties:
cursor:
type: string
feeds:
type: array
items:
$ref: '#/components/schemas/AppBskyFeedDefsGeneratorView'
examples:
FeedGetActorFeedsResponse200Example:
$ref: '#/components/examples/FeedGetActorFeedsResponse200Example'
'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.feed.getActorLikes:
get:
operationId: feedGetActorLikes
summary: Bluesky Get a list of posts liked by an 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 posts liked by an actor. Requires auth, actor must be the requesting account.
tags:
- Feeds
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:
- feed
properties:
cursor:
type: string
feed:
type: array
items:
$ref: '#/components/schemas/AppBskyFeedDefsFeedViewPost'
examples:
FeedGetActorLikesResponse200Example:
$ref: '#/components/examples/FeedGetActorLikesResponse200Example'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
required:
- error
- message
properties:
error:
type: string
enum:
- InvalidRequest
- ExpiredToken
- InvalidToken
- BlockedActor
- BlockedByActor
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.feed.getAuthorFeed:
get:
operationId: feedGetAuthorFeed
summary: Bluesky Get a view of an actor's 'author feed' (post and reposts by the author).
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 view of an actor's 'author feed' (post and reposts by the author). Does not require auth.
tags:
- Feeds
x-microcks-operation:
delay: 100
dispatcher: FALLBACK
dispatcherRules: ''
security:
- Bearer: []
# --- truncated at 32 KB (662 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bluesky/refs/heads/main/openapi/bluesky-openapi.yml