I am so, so excited about today's release of the Bluesky Protocol Services site that I had no choice but to write my own separate blog post on top of the official atproto.com announcement!
This project kicked off toward the end of June, so it's been in flight for nearly two months, and during that time I kept rotating off and on to it, looking forward to when it would ship. It represents the last piece of our docs overhaul that began with atproto.com and continued with https://endpoints.bsky.app/, all of which have been more or less my babies in the ten or so months that I've been here at Bluesky. As of today, I'm confident that we no longer have any docs that point to deprecated or less-than-ideal solutions, or that wouldn't give a user a mistaken impression of how to scale up on Atmosphere development. The docs debt is paid! But this project cleans up more than just docs-related technical debt.
One reason (apart from my colleagues having the gall to get married this summer, ahem) that this took as long as it did to ship is because we kept adding to the technical stack that we were bringing up as we rewrote these docs:
The bones of Bluesky Protocol Services are built on the old https://docs.bsky.app/ — the goal here was always to have a home for Bluesky's own service offerings and narrowly-scoped App SDKs, separate but complementary with the broader Atmosphere. That hasn't changed, but it's notable that a) the early Bluesky Docs largely predated the dedicated atproto documentation and there was a lot of redundant or ambivalent framing of what was a Bluesky service vs. a protocol feature, and b) we now have a few more things that fit in the category of "Bluesky service."
Hence this new homepage grid!
Jetstream v2 was the primary motivator to launch BPS as a new brand identity — we are getting more serious about being a large-scale data provider and improving the ergonomics of working with Atmosphere data in aggregate. We are really excited about this, it is unambiguously the topline, banner feature here, and most of the net-new content on this site covers several new use cases for Jetstream, including a dedicated SDK and documentation of its new Replay features.
But Jetstream was a much smaller piece of the old https://docs.bsky.app/, and after carving out all of the pieces of that site that now belonged elsewhere, the major one to still account for was, of course, the Bluesky API documentation.
That's all this stuff right here, which I've now put a box around in the sidebar to visually distinguish it, to avoid breaking the expectations of developers who want to use this site for classic "how do I make a post with the API" get started questions.
Two big things came out of this: one, the old Bluesky SDK was outdated as it had never been rebased on lex (and that was causing observable problems for LLMs which would recommend outdated SDK patterns based on our not-explicitly-deprecated docs), and two, we didn't want this to be the main "Get Started" path anymore either way. We expect that developers will come to the Atmosphere, and to Bluesky's services, with many different sets of expectations; some may want to create a Bluesky client that's shaped like other social media apps, dashboards, bots, and so on, but others may just be here for Jetstream, and skip the Bluesky APIs entirely.
So we needed a new first-touch funnel.
This took the form of a brand new sensemaking Get Started page that routes you across the site (and across the API surfaces) right after the homepage, but points mainly at Jetstream for new devs.
We reused and improved our live Jetstream sample from the atproto.com homepage here, which also gave us an excuse to create an isomorphic WebSocket client that could be used both in the browser and in the new Jetstream SDK.
We also made a little "scrollyteller" to show off the atproto Lexicon fundamentals here:
Partially this was because we don't get into the nuts and bolts of Lexicons on BPS — but needed a brief explainer before people go all the way into atproto-land — and partially this was because we wanted to show off the different Lexicon slicing capabilities of Jetstream while emphasizing the fun parts (the different apps on the network).
Getting back to the Bluesky SDK — shipping this new site surfaced our a longstanding need to rebase the Bluesky SDK onto lex, which... we went ahead and did! The devex is, intentionally, not significantly different, but this is a much bigger update behind the scenes than it appears. There's shouldn't be many more BskyAgent patterns using the old SDK floating around in the wild after this, which means that any developers who are writing Bluesky client code will be starting from a Lexicon-native base that can easily serve as a client for more than just Bluesky. If you ask Claude for Bluesky API code today, there's a decent chance you'll still get BskyAgent, but with this change, we expect that technical debt to soon disappear.
There are two other new pages I particularly want to draw attention to. One is on Request Proxying:
This is one of those atproto concepts that we try to avoid explaining up front because it's a bit unintuitive. Essentially, if you're using an authenticated API client, that client makes requests directly to your PDS after resolving your identity, and the PDS may or may not proxy those requests through the PDS to the Bluesky app (instead of just writing to the PDS itself), based on fairly arbitrary optimization logic. If you're using an unauthenticated client, which we also encourage, you don't go through a PDS at all, and just hit the App directly, but it's hard for novice developers to tell which endpoints are implemented on the PDS vs the App because they don't need to unless they're implementing their own app or PDS — in which case they learn about edge cases they don't like. This is also why https://endpoints.bsky.app/#bluesky-app/ lists com.atproto and app.bsky endpoints on the same tab; they don't split that cleanly in practice.
We wanted to take a better crack at actually addressing this for developers who explicitly want strict proxying behavior, while keeping it out of others' way. On the axis of "code around it" vs. "document around it" I think we've done a nice job here, and if you ever need to think about PDS request proxying, you finally have a stable resource for that.
The other page is our new list of community project integrations into the Bluesky app. This is something we found ourselves wanting in Devrel on a pretty regular basis, to help explain our baseline requirements for these projects, and to articulate where these integration surfaces are standards-driven and potentially self-serve (as in the case of Standard.site).
All in all, we have some big new improvements here, and a much cleaner narrative around Bluesky's service offerings and how they relate to the broader Atmosphere. This site now actually goes into less detail on what a PDS is, or how moderation works, than before; that belongs on https://atproto.com/guides/the-at-stack, and is linked throughout.
I am so happy to have this shipped! The push to modernize the Bluesky SDK was overdue icing on the cake, just like the push to move the OpenAPI documentation onto https://endpoints.bsky.app/. Our project has grown a lot in the last few years, and we have a much clearer idea now of where Bluesky's service boundaries are within the ecosystem; it's nice to have this in writing, and to no longer have any associated "oh, we should really update that" papercuts.
Speaking for myself and the docs (I am a bit like the Lorax in this respect), it feels great to be embarking on our upcoming permissioned data push with a totally clean slate, no fires to put out, nothing shaming me for outdated work. And now I'm off to run a booth at https://www.hope.net/ this weekend — looking forward to your feedback next week :)