DOCSEARCHbyAlgolia
Submit Docs

Bluesky Documentation

website·Indexed 20 days ago

https://docs.bsky.app/

Developer documentation for building on the AT Protocol and Bluesky network. Includes tutorials for creating posts, managing profiles, following users, and viewing feeds, as well as advanced guides on PDS federation architecture, OAuth clients, firehose streams, Lexicon API definitions, and moderation labels.

Tokens
52.8K
Snippets
176
Records
393
Agent score
99%

What's inside Bluesky

  1. Overview of Jetstream for atproto data streaming

    Jetstream is an alternative streaming solution to the standard atproto firehose. While the firehose provides an aggregated stream of all public data updates, it uses a complex binary format (CBOR and CAR files). Jetstream simplifies this by consuming from the firehose and fanning out to subscribers using simple JSON encoding, reduced bandwidth, and compression. It allows developers to filter the stream by collection (NSID) or repository (DID), making it more efficient for projects that only need a subset of network events.

  2. Overview of OAuth for AT Protocol

    OAuth is the primary authentication and authorization system for atproto client apps and PDS instances, replacing the legacy App Password and createSession flow. Due to the decentralized nature of the atproto network (multiple independent server instances and clients), the implementation requires automated discovery of the user's Authorization Server and automated registration of client metadata. This specific profile may not be compatible with generic OAuth client libraries out-of-the-box.

  3. Overview of Bluesky Labeling Services and Stackable Moderation

    Bluesky utilizes a stackable moderation ecosystem where users and communities can subscribe to filters from independent labeling services. These third-party services layer on top of Bluesky's own internal moderation team and community guidelines, allowing for diverse, culture-specific, and community-driven moderation norms.

  4. Overview of Bluesky's proposed secure contact import design

    Bluesky is designing a secure, double opt-in system for finding friends via phone contact imports. The system is designed to prevent PII leaks and enumeration attacks. Key privacy guarantees include:

    • Double Opt-in: A user will only be findable if they have explicitly opted in and verified their own phone number.
    • Revocable Consent: Users can remove all uploaded contact data from servers.
    • Purpose Limitation: Uploaded data is used exclusively for finding contacts on Bluesky.
    • Mutual Discovery: A match is only suggested if User A has User B's number in their contacts AND User B has User A's number in theirs.

  5. Overview of Bridgy Fed

    Bridgy Fed is an open-source bidirectional bridge between decentralized social networks. It allows users on supported networks to follow users on other networks, view posts, and engage via replies, likes, and reposts, with interactions flowing across networks in both directions. Current and planned support includes the IndieWeb, the Fediverse (e.g., Mastodon), Bluesky (AT Protocol), and Nostr.

  6. Overview of SkyFeed and SkyFeed Builder

    SkyFeed is a third-party web client for Bluesky that provides a dashboard-like experience (similar to TweetDeck) for managing feeds and profiles. It features real-time updates for like/reply/repost counts by subscribing to a minimal version of the Bluesky firehose and includes a collapsible thread view for easier navigation of large discussions.

    The integrated SkyFeed Builder is a tool designed to allow both developers and non-developers to create custom feeds using regexes or lists without needing to build a feed generator from scratch.

  7. Overview of Tap synchronization tool

    Tap is a single-tenant service written in Go that sits between the AT network firehose and an application. It synchronizes subsets of the Atmosphere (or the entire network) by subscribing to a Relay and outputting filtered, verified repository events as JSON. It solves common sync challenges such as automatic backfilling of repository history, MST integrity checks, identity signature verification, and automatic recovery from desynchronized states.

  8. Understand AT Protocol (atproto) core concepts

    The AT Protocol (Authenticated Transfer Protocol) is an open-source framework for building federated social apps. It standardizes user identity, follows, and data to allow interoperability and account portability across different applications and servers.

  9. Use the Agent class hierarchy for forward compatibility

    The @atproto/api package has introduced a new class hierarchy to support modular session management and future OAuth implementation. To ensure forward compatibility, use the Agent type for function parameters and class properties where an agent is expected, and use AtpAgent only for instantiation.

    Hierarchy:

    • XrpcClient: The base class for XRPC communication.
    • AtpBaseClient (formerly AtpServiceClient): Extends XrpcClient; adds typed lexicon namespaces.
    • Agent: Abstract class extending AtpBaseClient; adds session management methods and atproto utilities (labelers, proxy headers, cloning).
    • AtpAgent: Extends Agent; provides password-based session management.
    • BskyAgent: Extends AtpAgent (Deprecated; use AtpAgent instead).
    import { Agent, AtpAgent } from '@atproto/api'

// Use AtpAgent for instantiation
async function setupAgent(service: string, username: string, password: string): Promise<Agent> {
  const agent = new AtpAgent({
    service,
    persistSession: (evt, session) => { /* handle session update */ },
  })
  await agent.login(username, password)
  return agent
}

// Use Agent type for consumption to remain compatible with future OAuth agents
async function doStuffWithAgent(agent: Agent, arg: string) {
  return agent.resolveHandle(arg)
}

  10. Understand the Public Ledger of Credentials (PLC) identity system

    The Bluesky Social app and the AT network use Decentralized Identifiers (DIDs) to refer to users. The primary DID method used is the Public Ledger of Credentials (PLC), a general-purpose identity system that relies on a global directory service to distribute identity updates. The PLC system is designed to be vendor- and application-neutral, allowing it to be used by projects beyond the AT network.

  11. Understand the role of the Relay in AT Protocol

    The Relay is responsible for 'big-world' networking. It crawls the network to gather data and outputs it as a single large stream (firehose) for other services to consume. Relays can be full-network providers or partial-network providers servicing specific communities or applications. Because they are resource-demanding, they typically act as the primary aggregators of network data.

  12. Understand how blocks are implemented in Bluesky

    Blocks in Bluesky are implemented as public, enumerable records stored within a user's account repository. They are part of the app.bsky.* application protocol and are built on the AT Protocol (atproto). Because Bluesky is a federated network, block records must be public so that all servers, Personal Data Servers (PDS), App Views, and clients can read and respect the block to prevent disallowed interactions.

    Key characteristics of Bluesky blocks:

    • Symmetric Interaction: Blocked accounts cannot like, reply to, mention, or follow the blocker.
    • Visibility: If a blocked user navigates directly to the blocker's profile, they will see that they have been blocked.
    • Public Data: Because records are public, developers using the API can potentially crawl the network to identify block relationships.
    • Non-Destructive: Blocking does not delete existing content (like old replies) from the blockee's repository; it only hides that content from the blocker's view and prevents new interactions.