Building apps on Bluesky's ATProtocol opens up a world of possibilities for social networking applications. Whether you want to create a custom Bluesky client, build tools to track trending hashtags, or develop features to help users grow their Bluesky reach, this tutorial will get you started.

What is ATProtocol and Why Build on Bluesky?

The AT Protocol (Authenticated Transfer Protocol) is an open, decentralized protocol for social networking. Unlike traditional social platforms, ATProtocol gives users control over their identity and data. This openness creates opportunities for developers to build innovative tools that weren't possible on closed platforms.

With Bluesky's growing user base, now is the perfect time to build apps that help users:

  • Discover trending content and hashtags
  • Increase their visibility and grow their following
  • Monitor keywords and topics relevant to their interests
  • Engage more effectively with their community

Key Bluesky API Concepts You Need to Know

Before diving into code, it's important to understand these fundamental concepts:

  • DID (Decentralized Identifier) - A unique identifier for each user that persists across servers. DIDs look like did:plc:xyz123... and are the permanent way to identify accounts.
  • Handle - A human-readable username (like @username.bsky.social). Handles can change, but DIDs remain constant.
  • PDS (Personal Data Server) - Where a user's data is stored. Most users are on bsky.social, but the protocol supports self-hosting.
  • Lexicons - Schema definitions for data types and API endpoints. These define the structure of posts, profiles, and other data.

Authenticating with the Bluesky API

To interact with a user's data or build features like trending hashtag tracking, you'll need to authenticate. The most common approach is using an app password:

// Bluesky API Authentication Request
POST https://bsky.social/xrpc/com.atproto.server.createSession
Content-Type: application/json

{
    "identifier": "your-handle.bsky.social",
    "password": "your-app-password"
}

// Response includes accessJwt and refreshJwt tokens

Pro tip: Always use app passwords instead of your main password. You can create app passwords in your Bluesky account settings.

Fetching a User's Bluesky Timeline

Once authenticated, you can fetch a user's timeline to display posts, analyze engagement patterns, or build recommendation features:

// Get the authenticated user's timeline
GET https://bsky.social/xrpc/app.bsky.feed.getTimeline
Authorization: Bearer {accessJwt}

// Optional parameters:
// ?limit=50 (max 100)
// ?cursor={cursor} (for pagination)

Finding Trending Content on Bluesky

One of the most valuable features you can build is trending content discovery. While Bluesky doesn't have a built-in trending API, you can:

  • Connect to the Bluesky Firehose to stream all public posts in real-time
  • Track hashtag usage patterns to identify what's trending
  • Analyze engagement metrics to surface popular content
  • Build keyword monitoring to alert users about topics they care about

We built Skyscraper's Trending Hashtags tool using exactly these techniques, processing millions of posts to show what's popular right now.

Tips for Growing Bluesky Reach with Your App

If you're building tools to help users grow their Bluesky presence, consider these features:

  • Hashtag suggestions - Help users discover relevant trending hashtags to include in their posts
  • Best time to post - Analyze engagement patterns to suggest optimal posting times
  • Engagement analytics - Show users which content performs best
  • Keyword alerts - Notify users when topics they care about are being discussed

Next Steps in Your Bluesky Development Journey

This tutorial covered the basics, but there's much more to explore:

  • Creating posts - Learn to post text, images, and links via the API
  • Working with media - Upload and embed images and videos
  • Building custom feeds - Create algorithmic feeds that users can subscribe to
  • Real-time updates - Connect to the firehose for live data streaming
  • Moderation tools - Build safety features using Bluesky's labeling system

Explore Bluesky Trends with Skyscraper

Want to see what's trending on Bluesky right now? Check out our free tools:

Happy building, and welcome to the Bluesky developer community!