Table of Contents

Concepts & Common Terms

This documentation contains some common terms that you will see when discussing AT Protocol and Bluesky APIs.

at:// uri, cid, and Strong References

If you looked at the return value from agent.Post() you would have seen that the API returns some information, including a StrongReference, a Uri and a Cid.

at:// uris

This is not an HTTPS URI, it is an at:// uri. An at:// uri is a reference to a record on the network.

It is made up of three parts, an authority, a collection and a record key:

"at://" AUTHORITY [ "/" COLLECTION [ "/" RKEY ] ]

The authority is a DID, which is who or what owns the content, the collection is used as a grouping of record types, and the rKey is the key to the individual record.

CID

This is a content identifier, a way to reference a revision of a record pointed to by an at:// uri. It is implemented as a hash of the record.

StrongReference

A StrongReference is a record contain both the at:// uri of a record, and its CID.

Repositories

Bluesky stores all your stuff in a repository on a Personal Data Server (PDS). A repository contains various collections, and these collections contain records. For example, when you write a post you are creating a record in your repository in the app.bsky.feed.post collection.

A simple post record would, in JSON, look something like this

{
  "text": "Hello World!",
  "$type": "app.bsky.feed.post",
  "createdAt": "2023-08-07T05:31:12.156888Z"
}

The shape of a record is defined by the lexicon, for example you can find the definition for a post record in the Bluesky Feed lexicon.

Records, Collections and NSIDs

Collections are identified by namespace identifiers (NSIDs), which make up part of the at:// uri.

A record can be referred to by its (strong reference)[#strongReference], or by an at:// uri.

If we examine an at:// uri, for example, at://sinclairinat0r.com/app.bsky.feed.post/3l5ptjwzotx2h, we can break it down into the following parts

  • An authority of sinclairinat0r.com, which can also be read as the repository name.
  • A collection of app.bsky.feed.post, the NSID of the collection the record is in. In this case it's in the post repository, which contains all the users posts.
  • A record key of 3jwdwj2ctlk26, a key to the latest version an individual post in the record collection.

Records can, according to the AT Protocol, have multiple versions. A (strong reference)[#strongReference] contains not only an at:// uri but also a CID which refers to a individual revision of a record.

Actors, handles and DIDs

The Bluesky API documentation refers to a user or bot account as anActor. Actors can be identified in one of two ways, a handle and a Distributed Identifier (DID)

Handles

A handle is what you see in human readable terms, for example "blowdart.me". It's how you view a profile in the browser, for example https://bsky.app/profile/blowdart.me and it's how you @ people in posts.

However as you may have discovered handles can change. When registering on Bluesky you register with a something.bsky.social handle, which you can then change to be DNS "verified". If you change your handle your posts still remain, and people that follow you keep following you through the change. This is because underneath handles aren't often used by the APIs, an account is referenced by its DID.

Distributed Identifier (DID)

A DID is your unique key on the atproto network. Under the covers Bluesky uses DIDs, not handles for pretty much everything, sometimes accepting both and doing the work behind the scenes to resolve a handle into a `DID``.

A DID looks something like this: did:plc:hfgp6pj3akhqxntgqwramlbg. The first part of the DID is the prefix declaring it's a DID, the second part is an identifier for the issuer (plc is a DID issued by Bluesky, web is another common identifier indicating an independently issued DID), and the final part is a unique reference issued by the issuer.

For example, the api to get an actor profile takes a DIDor a handle (this either/or combination is represented as an At-Identifier), but things like updateAccountPassword take just a DID.

When you login via an agent the authenticated user's DID is available via the Did property on the agent instance.

Bluesky's DID directory is available at https://web.plc.directory/. It servers up a DidDoc for a plc DID which allows discovery of things like a DID's personal data server where authenticated API calls should go. The BlueskyAgent class take care of PDS discovery automatically, but you can retrieve a DidDoc yourself using the DirectoryAgent ResolveDidDocument method.

Resolving a Handle to a DID

The AtProto and Bluesky agents provide a method to resolve a DID for a Handle, ResolveHandle().

Views

As you explore the APIs you while you write records you don't get records, instead you get views of records. You create a Post but what you see in your timeline is a PostView.

A view is how Bluesky aggregates information from multiple records into a single entity. For example a PostView takes information from not only the Post record, but also information about the post author via a ProfileView, and things like reply and like counts. If you've used a SQL database before you can think of a view like a select over multiple joined tables.

Views are generated by applications, the overall view over data that Bluesky presents is commonly referred to as the AppView.

Edit this page