AT Protocol Usage Examples

A reference project for developers learning the AT Protocol (atproto) with @atproto/api, the official TypeScript SDK.

Each module is self-contained, documented, and focused on a specific area of the protocol. Use it as a starting point for your own integrations or as material for internal knowledge sharing.

Examples

Module	Description	Key AT Protocol Concepts
auth	App Password authentication with a PDS	PDS, DID, Handle, App Passwords, CredentialSession
post	Creating records (posts, likes, reposts, replies)	Records, Lexicons, app.bsky.feed.post, AT URIs, CIDs
feed	Reading timelines, author feeds, threads, search	App View, Relay, pagination cursors
profile	Reading/updating profiles, follows, handle resolution	Actor records, app.bsky.actor.profile, app.bsky.graph.follow
richtext	RichText facets: mentions, links, grapheme handling	Facets, byte-slice annotations, UTF-8 vs UTF-16
moderation	Label system, preferences, mute/block	Speech vs Reach, labelers, content labels, moderation API

Knowledge UI

A browser-based knowledge base (Stack Overflow + Reddit style) for browsing source-backed AT Protocol notes:

cd ui && npm install && npm run dev

Or from the project root:

npm run ui

Open http://localhost:5173 to browse questions, discussions, and source snippets mapped to each module.

Quick Start

Prerequisites

• Node.js 18+
• A Bluesky account (bsky.app)
• An App Password (do not use your main account password)

Setup

git clone <repo-url> atproto-usage-example
cd atproto-usage-example

npm install

cp .env.example .env
# Edit .env with your Bluesky handle, App Password, and PDS URL

Run

# Run a specific example
npm run demo:auth
npm run demo:post
npm run demo:feed
npm run demo:profile
npm run demo:richtext
npm run demo:moderation

# Run all examples
npm run demo:all

Project Structure

src/
├── index.ts        # Entry point and example runner
├── auth.ts         # App Password authentication
├── post.ts         # Record creation (posts, replies, likes, reposts)
├── feed.ts         # Feed reading (timeline, author, thread, search)
├── profile.ts      # Actor profile management
├── richtext.ts     # RichText facets, mentions, links, grapheme handling
└── moderation.ts   # Moderation preferences and label system

AT Protocol Concepts Covered

1. Identity and Authentication

• DIDs (Decentralized Identifiers): permanent, server-independent identities (did:plc:...)
• Handles: human-readable domain names mapped to DIDs (@alice.bsky.social)
• PDS (Personal Data Server): hosts your identity and data repository
• App Passwords: scoped credentials for programmatic access

2. Data Repositories and Records

• Records: the fundamental data unit stored in signed repositories
• Collections: namespaced record types (e.g., app.bsky.feed.post)
• Lexicons: schema definitions that standardize record types across the network
• AT URIs: at://did/collection/rkey format for uniquely identifying records
• CIDs: content hashes for content-addressed referencing

3. Network Architecture

• PDS, Relay, App View: the three-tier federation model
• Federation: servers communicate over standard HTTP (XRPC) and WebSockets
• Cursors: pagination tokens for fetching additional data pages

4. RichText System

• Facets: byte-slice annotations on text segments
• Mention facets: references to actor DIDs (app.bsky.richtext.facet#mention)
• Link facets: annotated URLs (app.bsky.richtext.facet#link)
• Grapheme handling: AT Protocol uses UTF-8 graphemes (not UTF-16 code units)

5. Moderation

• Speech vs Reach: separate layers for openness and curation
• Labels: metadata annotations by independent labeler services
• Moderation preferences: user-configured label handling (hide, warn, show)
• Mute/Block: personal and community-driven content filtering

Resources

• AT Protocol Docs
• AT Protocol Specs
• Bluesky API Docs
• Official Cookbook
• @atproto/api on npm

License

CC0-1.0 — Public Domain Dedication. Copy freely, no attribution required.

Dependencies (including @atproto/api) have their own licenses (MIT/Apache 2.0 dual).