AT URIs and bsky.app links, explained
The at:// URI grammar for developers: authority, collection NSID and record key, how bsky.app links map to AT URIs, and how to convert them in code.
What an AT URI names
An AT URI points to an account or to one record of its repository. It is the address apps and APIs use, where people use bsky.app links. Its grammar, from the AT URI spec:
at://AUTHORITY/COLLECTION/RKEY- Authority: the account, as a DID (
did:plc:…,did:web:…) or a handle. Records are stored by DID, so a stored URI should always use the DID: a handle can change hands. - Collection: the record type, an NSID such as
app.bsky.feed.post. - Record key (
rkey): the record's name in its collection. Most are TIDs, timestamp identifiers such as3l6oveex3ii2l; a profile is alwaysself.
at://did:plc:z72i7hdynmk6r22z27h6tvur is an account, at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post all its posts, and a third part names one post. The URI has no query and no fragment in the records the converter reads.
From bsky.app to at:// and back
The Bluesky app gives five kinds of records a page. The converter maps them both ways:
| bsky.app link | AT URI |
|---|---|
/profile/{actor} | at://{did} |
/profile/{actor}/post/{rkey} | at://{did}/app.bsky.feed.post/{rkey} |
/profile/{actor}/feed/{rkey} | at://{did}/app.bsky.feed.generator/{rkey} |
/profile/{actor}/lists/{rkey} | at://{did}/app.bsky.graph.list/{rkey} |
/starter-pack/{actor}/{rkey} | at://{did}/app.bsky.graph.starterpack/{rkey} |
{actor} is a handle or a DID: bsky.app accepts both. A link with the DID never breaks when the account changes its handle. Records of other collections (a like, a follow, a record of another app) have no bsky.app page: the converter gives their AT URI and its parts only.
To turn a handle into a DID, the converter asks Bluesky's AppView (com.atproto.identity.resolveHandle). To show a link with the handle, it reads the DID document and keeps the handle only when that handle resolves back to the same DID.
Convert in code
In TypeScript, AtUri from @atproto/syntax parses and builds URIs. A post link becomes its URI like this:
import { AtUri } from "@atproto/syntax";
const COLLECTIONS: Record<string, string> = {
post: "app.bsky.feed.post",
feed: "app.bsky.feed.generator",
lists: "app.bsky.graph.list",
};
export function postLinkToAtUri(link: string, did: string): string {
const [, , kind, rkey] = new URL(link).pathname.split("/").filter(Boolean);
const collection = COLLECTIONS[kind];
if (!collection || !rkey) throw new Error("Not a post, feed or list link");
return AtUri.make(did, collection, rkey).toString();
}
const uri = new AtUri("at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3l6oveex3ii2l");
uri.host; // the DID
uri.collection; // "app.bsky.feed.post"
uri.rkey; // "3l6oveex3ii2l"In Python, the AT URI is simple enough to split by hand:
def parse_at_uri(uri: str) -> dict:
if not uri.startswith("at://"):
raise ValueError("not an AT URI")
parts = uri[len("at://"):].split("/")
return {
"authority": parts[0],
"collection": parts[1] if len(parts) > 1 else None,
"rkey": parts[2] if len(parts) > 2 else None,
}Resolve the handle to a DID first (resolveHandle, or the DID finder) so that the URI you store keeps working.
From the API or an AI agent
The converter is also GET /api/v1/tools/at-uri-converter?uri=… and the MCP tool convert_at_uri: see Tools API and MCP server. When the record key is a TID, the TID decoder reads the time it encodes.