DOCSEARCHbyAlgolia
Submit Docs

Bluesky Developer Documentation

repository·main·Indexed 42 days ago

https://github.com/bluesky-social/bsky-docs

Developer guides and HTTP API references for Bluesky, built on the AT Protocol. Includes instructions for authenticating via com.atproto.server.createSession, creating posts using com.atproto.repo.createRecord, managing facets for mentions and links, uploading blobs for image embeds, and implementing block records via the app.bsky.graph.block schema.

Tokens
64.5K
Snippets
156
Records
321
Agent score
54%

What's inside Bluesky

  1. What is the AT Protocol (atproto)?

    main
    The AT Protocol (Authenticated Transfer Protocol) is an open-source framework and standard for public conversation. It provides a standardized format for user identity, social graphs (follows), and data, enabling interoperability between different social applications and allowing users to move their accounts across providers (account portability) without losing their data.

  2. Overview of Bridgy Fed

    main

    Bridgy Fed is an open-source bridge between decentralized social networks. It is designed to enable bidirectional interactions (following, posting, replying, liking, and reposting) between different protocols.

    Currently, it supports:

    • IndieWeb
    • Fediverse (e.g., Mastodon)
    • Bluesky (initial support complete)

    Planned future support includes Nostr and extending IndieWeb support to any website via OGP, RSS, and Atom feeds.

    Technical Stack:

    • Language: Python
    • Platform: Google App Engine (serverless)
    • Key Libraries/Standards: Granary, webmention, microformats2, ActivityPub, and AT Protocol (atproto).

  3. Introduction to Jetstream streaming

    main

    Jetstream is an alternative streaming solution to the standard atproto firehose. It is designed to be more efficient and easier to use for developers who do not require full cryptographic verification of every event.

    Key Advantages:

    • Simple JSON encoding: Unlike the standard firehose which uses binary CBOR and CAR files, Jetstream uses JSON.
    • Reduced bandwidth: Optimized for lower data consumption and compression.
    • Filtering capabilities: Allows subscribers to filter streams by collection (NSID) or repository (DID).

    Public Jetstream Instances:

    • jetstream1.us-east.bsky.network
    • jetstream2.us-east.bsky.network
    • jetstream1.us-west.bsky.network
    • jetstream2.us-west.bsky.network

    Implementation Details:

    • It is an open-source project implemented in Go.
    • It consumes from the full firehose and fans out to multiple subscribers.
    • Official Go client libraries are available, along with community libraries like skyware.js.

  4. Overview of SkyFeed community project

    main

    SkyFeed is a third-party Bluesky client and feed creation tool developed by redsolver. It provides two primary functions:

    1. SkyFeed Web App: A cross-platform client (similar to TweetDeck) that uses a custom minimal version of the Bluesky firehose to provide real-time updates for likes, replies, reposts, and new posts. It also features a collapsible thread view for easier discussion tracking.
    2. SkyFeed Builder: A tool designed to simplify the creation of custom Bluesky feeds. It allows both developers and non-developers to build feeds using regexes, lists, and a block-based query engine, lowering the barrier to entry compared to building a feed generator from scratch.

    You can access the app at https://skyfeed.app/.

  5. Understand Bluesky rate limits and error handling

    main

    Bluesky uses rate limits to prevent spam and brute-force attacks. Most HTTP API services return rate limit headers to help developers debug, automate request throughput, and implement backoff strategies. When a limit is exceeded, the service will typically return an HTTP 429 ("Too Many Requests") status code.

    Note that because Bluesky is built on the open atproto network, different providers in the network may have different rate-limiting policies.

  6. Summary of contact discovery security features

    main

    The Bluesky contact discovery system is designed to be resistant to data misuse through three primary mechanisms:

    1. Verification of the user’s own phone number: Ensures the user actually owns the number they are using for discovery.
    2. Mutual contact discovery only: The system only reveals contacts that are common to both the user's list and the existing database, preventing enumeration.
    3. Brute-force-resistant pairwise hashing: Hashes are paired and bound to a secret stored in a Hardware Security Module (HSM).

    This design aims to resist API-level enumeration and mitigate the impact of a full database compromise.

  7. Understand the AT Protocol (atproto) Roadmap

    main

    The AT Protocol (atproto) development roadmap focuses on transitioning the network toward federation. Key development priorities include:

    • Federation Readiness: Resolving protocol issues related to independent PDS (Personal Data Server) instances, including account migration, auth refactors (OAuth2/UCANs), and firehose (Repo Event Stream) optimizations.
    • Operational Scaling: Moving from a monolithic database to multiple PDS instances and transitioning firehose consumers from direct PDS feeds to a unified BGS (Bluesky Gateway Service) feed.
    • Application Development: Improving the Lexicon schema system, including automated schema resolution, clarifying validation failure behaviors, and documenting schema evolution/extension rules.
    • Future Features: Long-term goals include end-to-end encrypted (E2EE) private messaging, record versioning for history/edits, and support for static CAR file repository hosting.

  8. Bluesky AppView limits

    main

    Clients can connect directly to the Bluesky AppView at https://api.bsky.app or https://public.api.bsky.app. These endpoints do not support authentication.

    For "public web" use cases, developers are requested to use the public.api.bsky.app endpoint as it is cached. These services have generous rate limits; contact Bluesky if you encounter limiting.

  9. Planned atproto protocol improvements

    main

    The following protocol features are planned for future development but are not currently scheduled for completion in 2024. These represent the long-term roadmap for the atproto ecosystem:

    • Protocol-Native DMs: A decentralized, end-to-end encrypted (E2EE) direct messaging solution built into atproto.
    • Limited-Audience (Non-Public) Content: A mechanism for group-private content sharing that is distinct from the public data repository and Relay/firehose mechanisms.
    • Firehose Bandwidth Efficiency: Improvements to reduce the cost of subscribing to the Relay firehose, including removing MST metadata, filtering by record types or account subsets, and batch compression.
    • Record Versioning (Post Editing): Support for post editing that avoids misleading edits, potentially allowing repositories to retain and reference multiple versions of the same record.
    • PLC Transparency Log: A mechanism to further decentralize the DID PLC directory service by publishing a transparency log of all directory operations (potentially compatible with RFC 6962 Certificate Transparency).
    • Identity Key Self-Management UX: Improved UX for registering additional rotation keys on personal devices, password managers, or hardware security keys to improve identity resilience.

  10. What is Tap and when to use it

    main

    Tap is a single-tenant service written in Go designed for synchronizing subsets of the AT Atmosphere or mirroring the entire network. It sits between the full network firehose and your application, handling the complexities of repository synchronization.

    Key features include:

    • Automatic backfill: Automatically fetches complete history before delivering live events.
    • Verification: Handles MST integrity checks, identity signatures, and cryptographic validation.
    • Recovery: Automatically resyncs from the authoritative PDS if a repository becomes desynchronized.
    • Flexible delivery: Supports WebSocket connections (with acknowledgements), fire-and-forget mode, and webhooks for serverless environments.
    • Filtered output: Delivers events for specific repositories or collections as simple JSON.

    Use Tap when you need:

    • Automatic historical backfill for new repositories.
    • Native webhook support for serverless architectures.
    • Full network mirroring for research or analysis.
    • Guaranteed delivery via acknowledgement mode.
    • To track specific subsets of repositories without processing the entire firehose.

  11. What is the Firehose in AT Protocol

    main

    The firehose is a core primitive of the AT Protocol used to efficiently sync user updates such as posts, likes, follows, and handle changes. It is implemented as an authenticated stream of events.

    In the ecosystem, Personal Data Servers (PDS) serve streams for their own repositories, while relays aggregate these streams into a single unified stream. The main relay for Bluesky is bsky.network.

    Common use cases for the firehose include building feed generators, labelers, bots, and search engines.

  12. What is Service Auth in atproto

    main

    In the atproto network, Service Auth (service-to-service auth) is used when a service (like a PDS) makes a request to another service on behalf of a user. Unlike client-server auth, these tokens are asymmetrically signed JWTs.

    JWT Payload Structure:

    • iss: The user's DID (the issuer).
    • aud: The DID of the service receiving the request (the audience).
    • exp: The expiration date, typically set to a very short timeframe (less than 60 seconds).

    These tokens are signed using the signing key found in the user's DID document, which is the same key used to sign repository updates.