atproto.dart SDK

lex_gen is a Lexicon-to-Dart code generator that transforms Lexicon schema documents into Dart source code. It is the engine behind the atproto, bluesky, and bluesky_cli packages in this repository, ensuring the API surface remains in sync with the AT Protocol.

It is a library intended for use within a build script (like scripts/gen_codes.dart) rather than a standalone CLI tool.

Note: If you only need to parse or validate Lexicon documents at runtime, use the lexicon package instead.

The atproto.dart ecosystem consists of modular packages designed for different levels of the AT Protocol stack:

• bluesky: The primary toolkit for Bluesky-specific features like posts, feeds, chat, and moderation. Use this to start building social apps.
• atproto: Core AT Protocol support for building services beyond Bluesky.
• atproto_oauth: Implementation of OAuth 2.0 with DPoP for secure user sign-in.
• bluesky_text: Utilities for facet detection and accurate post-length counting.
• bluesky_cli: A command-line interface to interact with the APIs from your terminal.

Lower-level dependencies like at_primitives, xrpc, and multiformats are included automatically when using the higher-level packages.

The xrpc package implements the XRPC request layer of the AT Protocol. It is a thin wrapper around package:http that handles NSID-based addressing under /xrpc/, parses {error, message} error bodies, and processes ratelimit-* headers.

When to use xrpc directly:

• Calling a lexicon method not covered by the generated atproto or bluesky packages (including your own).
• Subscribing to an event stream that lacks a wrapper method.
• Writing a client for a service that speaks XRPC but is not a PDS or AppView.

When to use other packages:

• For com.atproto.* endpoints: use atproto.
• For app.bsky.* or chat.bsky.* endpoints: use bluesky.
• For sessions, retries, and the request pipeline: use atproto_core.

The atproto package provides the following core capabilities:

• Comprehensive API Coverage: Supports all major com.atproto.* endpoints.
• Service Agnostic: Works with any AT Protocol service, not just Bluesky.
• Multiple Authentication Methods: Supports session-based auth (with transparent refresh), OAuth 2.0 with DPoP, and anonymous access.
• Real-time Firehose API: Provides typed, decoded streams of live events from AT Protocol services.
• Pluggable Retry: Includes an idempotency-safe Exponential BackOff And Jitter policy via a RetryStrategy interface.
• Rate Limit Handling: Built-in detection and management of rate limits.
• Injectable Transport: Allows supplying a custom HTTP client for testing, proxies, or tracing.
• Type Safety: 100% null safety with support for complex AT Protocol union types.

The bluesky package provides several high-level capabilities for Bluesky development:

• Social Graph & Feed Operations: Management of posts, likes, reposts, timelines, follows, blocks, mutes, and lists.
• Chat API: Full support for conversation management and messaging (chat.bsky.*).
• Real-time Data: Support for the Firehose API for streaming data.
• Notifications: A rich notification system including client-side notification grouping that matches the official Bluesky app.
• Media: Video upload support with status tracking and limits management.
• Security: Support for OAuth DPoP for secure authentication.
• Reliability: Built-in retry logic using Exponential BackOff and Jitter with a pluggable RetryStrategy.
• Moderation: Comprehensive Moderation API for labeling and reporting.

Lists in the graph lexicon serve three primary purposes:

• modlist: A list of actors used to apply aggregate moderation actions like muting or blocking.
• curatelist: A list of actors used for curation, such as powering list feeds or gating interactions.
• referencelist: A list of actors used strictly for reference purposes, such as within a starter pack.

| Property | Type | Known Values | Required | Description |
| --- | --- | --- | :---: | --- |
| **listPurpose** | string | [app.bsky.graph.defs#modlist](../../../../lexicons/app/bsky/graph/defs.md#modlist)<br/>[app.bsky.graph.defs#curatelist](../../../../lexicons/app/bsky/graph/defs.md#curatelist)<br/>[app.bsky.graph.defs#referencelist](../../../../lexicons/app/bsky/graph/defs.md#referencelist) | ❌ | -

To create a reply in a Bluesky thread, include a reply object in your app.bsky.feed.post record. This object uses the replyRef structure, which requires two com.atproto.repo.strongRef references:

• root: The reference to the very first post in the thread.
• parent: The reference to the post being directly replied to.

Both root and parent are required for a valid reply structure.

When monitoring a video processing job via app.bsky.video.defs.jobStatus, use the state property to determine the current lifecycle stage.

Known States:

• JOB_STATE_CREATED
• JOB_STATE_ENCODING
• JOB_STATE_ENCODED
• JOB_STATE_SCANNING
• JOB_STATE_SCANNED
• JOB_STATE_UPLOADING
• JOB_STATE_UPLOADED
• JOB_STATE_COMPLETED
• JOB_STATE_FAILED

Note: Any value received that is not explicitly listed above indicates the job is currently in an active processing state.