Jetstream is a simplified JSON event stream for the AT Protocol that converts CBOR-encoded MST blocks from the firehose into JSON objects over WebSocket connections, making it easier to consume real-time Bluesky network events for building feed generators, bots, and search engines.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/bluesky-jetstream"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
asyncapi: '2.6.0'
info:
title: Bluesky / AT Protocol Event Streams
version: '1.1.0'
description: |
AsyncAPI definition for the public event streams of the Bluesky network and the
underlying AT Protocol.
Three streams are documented:
* **`com.atproto.sync.subscribeRepos`** - the primary repository event stream
("firehose"). Binary WebSocket frames carrying two concatenated DAG-CBOR
objects (header + payload). Implemented by every PDS and Relay; the public
Bluesky relay is reachable at `wss://bsky.network` (legacy) and
`wss://relay1.us-east.bsky.network` (Sync 1.1, with `prevData`).
* **`com.atproto.sync.subscribeLabels`** - the label / negation stream, served
by moderation services. Same binary CBOR frame format as `subscribeRepos`.
* **Jetstream** - a simplified JSON projection of the firehose. Plain
JSON-text WebSocket frames (optionally zstd-compressed). Operated by
Bluesky at `jetstream{1,2}.{us-east,us-west}.bsky.network`.
Schemas are reproduced verbatim from the upstream AT Protocol lexicons
(`com.atproto.sync.subscribeRepos`, `com.atproto.label.subscribeLabels`,
`com.atproto.label.defs`) and the `bluesky-social/jetstream` repository.
contact:
name: Bluesky Social PBC
url: https://bsky.social
email: support@bsky.app
license:
name: MIT
url: https://github.com/bluesky-social/atproto/blob/main/LICENSE.txt
termsOfService: https://bsky.social/about/support/tos
x-references:
- name: AT Protocol Event Stream specification
url: https://atproto.com/specs/event-stream
- name: AT Protocol Sync specification
url: https://atproto.com/specs/sync
- name: Bluesky Firehose advanced guide
url: https://docs.bsky.app/docs/advanced-guides/firehose
- name: subscribeRepos lexicon
url: https://github.com/bluesky-social/atproto/blob/main/lexicons/com/atproto/sync/subscribeRepos.json
- name: subscribeLabels lexicon
url: https://github.com/bluesky-social/atproto/blob/main/lexicons/com/atproto/label/subscribeLabels.json
- name: label defs lexicon
url: https://github.com/bluesky-social/atproto/blob/main/lexicons/com/atproto/label/defs.json
- name: Jetstream repository
url: https://github.com/bluesky-social/jetstream
defaultContentType: application/cbor
servers:
relay:
url: bsky.network
protocol: wss
description: |
Public Bluesky Relay firehose. Hosts the binary CBOR-framed
`com.atproto.sync.subscribeRepos` endpoint. Legacy endpoint; does not
emit the Sync 1.1 `prevData` field.
relay-sync-1-1:
url: relay1.us-east.bsky.network
protocol: wss
description: |
Bluesky Sync 1.1 relay. Same XRPC endpoints as `bsky.network`, but emits
the inductive-firehose `prevData` field and `#sync` events.
ozone:
url: mod.bsky.app
protocol: wss
description: |
Bluesky's Ozone moderation service. Hosts the binary CBOR-framed
`com.atproto.label.subscribeLabels` endpoint.
jetstream2-us-east:
url: jetstream2.us-east.bsky.network
protocol: wss
description: |
Public Jetstream instance (US-East). JSON projection of the firehose.
jetstream1-us-east:
url: jetstream1.us-east.bsky.network
protocol: wss
description: Public Jetstream instance (US-East).
jetstream1-us-west:
url: jetstream1.us-west.bsky.network
protocol: wss
description: Public Jetstream instance (US-West).
jetstream2-us-west:
url: jetstream2.us-west.bsky.network
protocol: wss
description: Public Jetstream instance (US-West).
channels:
#####################################################################
# com.atproto.sync.subscribeRepos
#####################################################################
xrpc/com.atproto.sync.subscribeRepos:
description: |
Repository event stream, aka Firehose endpoint. Outputs repo commits with
diff data, and identity update events, for all repositories on the
current server. Public; no auth. Implemented by PDS and Relay. Frames are
binary WebSocket messages consisting of two concatenated DAG-CBOR
objects: a header (`{op, t}`) followed by a payload whose shape depends
on `t`.
servers:
- relay
- relay-sync-1-1
parameters:
cursor:
description: The last known event seq number to backfill from.
schema:
type: integer
format: int64
bindings:
ws:
method: GET
query:
type: object
properties:
cursor:
type: integer
description: The last known event seq number to backfill from.
bindingVersion: '0.1.0'
subscribe:
operationId: subscribeRepos
summary: Subscribe to the repository event stream (firehose).
message:
oneOf:
- $ref: '#/components/messages/RepoCommitFrame'
- $ref: '#/components/messages/RepoSyncFrame'
- $ref: '#/components/messages/RepoIdentityFrame'
- $ref: '#/components/messages/RepoAccountFrame'
- $ref: '#/components/messages/RepoHandleFrame'
- $ref: '#/components/messages/RepoMigrateFrame'
- $ref: '#/components/messages/RepoTombstoneFrame'
- $ref: '#/components/messages/RepoInfoFrame'
- $ref: '#/components/messages/RepoErrorFrame'
#####################################################################
# com.atproto.label.subscribeLabels
#####################################################################
xrpc/com.atproto.label.subscribeLabels:
description: |
Subscribe to stream of labels (and negations). Public endpoint
implemented by mod services. Uses the same sequencing scheme as the
repository event stream and the same binary CBOR header/payload framing.
servers:
- ozone
parameters:
cursor:
description: The last known event seq number to backfill from.
schema:
type: integer
format: int64
bindings:
ws:
method: GET
query:
type: object
properties:
cursor:
type: integer
bindingVersion: '0.1.0'
subscribe:
operationId: subscribeLabels
summary: Subscribe to the label/negation stream.
message:
oneOf:
- $ref: '#/components/messages/LabelsFrame'
- $ref: '#/components/messages/LabelInfoFrame'
- $ref: '#/components/messages/LabelErrorFrame'
#####################################################################
# Jetstream
#####################################################################
subscribe:
description: |
Jetstream WebSocket endpoint. Emits a simplified JSON projection of the
AT Protocol firehose. Each WebSocket frame is one JSON event object
(optionally zstd-compressed if `compress=true` is set on the query).
servers:
- jetstream2-us-east
- jetstream1-us-east
- jetstream1-us-west
- jetstream2-us-west
bindings:
ws:
method: GET
query:
type: object
properties:
wantedCollections:
type: array
description: |
Filter events to only the listed collection NSIDs. Supports
NSID prefixes (e.g., `app.bsky.graph.*`). Up to 100 entries.
items:
type: string
wantedDids:
type: array
description: |
Filter events to only the listed repository DIDs. Up to 10,000
entries.
items:
type: string
format: did
maxMessageSizeBytes:
type: integer
description: |
Maximum payload size, in bytes. Zero (the default) is treated
as unlimited; negative values are treated as zero.
default: 0
cursor:
type: integer
format: int64
description: |
Unix microseconds timestamp to begin playback from. If absent
or in the future, the stream operates in live-tail mode.
compress:
type: boolean
description: When `true`, frames are zstd-compressed.
default: false
requireHello:
type: boolean
description: |
When `true`, the server pauses event delivery until the
client sends an `options_update` SubscriberSourcedMessage.
default: false
bindingVersion: '0.1.0'
subscribe:
operationId: jetstreamSubscribe
summary: Subscribe to the Jetstream JSON event stream.
message:
oneOf:
- $ref: '#/components/messages/JetstreamCommitCreate'
- $ref: '#/components/messages/JetstreamCommitUpdate'
- $ref: '#/components/messages/JetstreamCommitDelete'
- $ref: '#/components/messages/JetstreamIdentity'
- $ref: '#/components/messages/JetstreamAccount'
publish:
operationId: jetstreamSubscriberMessage
summary: |
Send a `SubscriberSourcedMessage` to update subscription options after
connecting. Currently supports the `options_update` message.
message:
$ref: '#/components/messages/JetstreamSubscriberSourcedMessage'
components:
messages:
#################################################################
# subscribeRepos frames
#################################################################
RepoCommitFrame:
name: RepoCommitFrame
title: '#commit'
summary: Repository commit event.
contentType: application/cbor
payload:
$ref: '#/components/schemas/RepoCommitFrame'
RepoSyncFrame:
name: RepoSyncFrame
title: '#sync'
summary: |
Sync event - asserts current repository state without including diff
data on the firehose. Used for recovery / desync resolution.
contentType: application/cbor
payload:
$ref: '#/components/schemas/RepoSyncFrame'
RepoIdentityFrame:
name: RepoIdentityFrame
title: '#identity'
summary: Account identity change event (handle, signing key, or PDS).
contentType: application/cbor
payload:
$ref: '#/components/schemas/RepoIdentityFrame'
RepoAccountFrame:
name: RepoAccountFrame
title: '#account'
summary: Account hosting-status change event.
contentType: application/cbor
payload:
$ref: '#/components/schemas/RepoAccountFrame'
RepoHandleFrame:
name: RepoHandleFrame
title: '#handle'
summary: DEPRECATED - use `#identity` instead. Legacy handle change event.
contentType: application/cbor
payload:
$ref: '#/components/schemas/RepoHandleFrame'
RepoMigrateFrame:
name: RepoMigrateFrame
title: '#migrate'
summary: DEPRECATED - use `#account` instead. Legacy account-migration event.
contentType: application/cbor
payload:
$ref: '#/components/schemas/RepoMigrateFrame'
RepoTombstoneFrame:
name: RepoTombstoneFrame
title: '#tombstone'
summary: DEPRECATED - use `#account` instead. Legacy account-tombstone event.
contentType: application/cbor
payload:
$ref: '#/components/schemas/RepoTombstoneFrame'
RepoInfoFrame:
name: RepoInfoFrame
title: '#info'
summary: |
Informational message (not persisted, no `seq`). Currently the only
defined name value is `OutdatedCursor`.
contentType: application/cbor
payload:
$ref: '#/components/schemas/InfoFrame'
RepoErrorFrame:
name: RepoErrorFrame
title: error
summary: |
Error frame (`op = -1`). Possible `error` values for subscribeRepos:
`FutureCursor`, `ConsumerTooSlow`. The connection is closed after this
frame is delivered.
contentType: application/cbor
payload:
$ref: '#/components/schemas/ErrorFrame'
#################################################################
# subscribeLabels frames
#################################################################
LabelsFrame:
name: LabelsFrame
title: '#labels'
summary: A batch of labels (and/or negations).
contentType: application/cbor
payload:
$ref: '#/components/schemas/LabelsFrame'
LabelInfoFrame:
name: LabelInfoFrame
title: '#info'
summary: Informational message on the label stream.
contentType: application/cbor
payload:
$ref: '#/components/schemas/InfoFrame'
LabelErrorFrame:
name: LabelErrorFrame
title: error
summary: |
Error frame (`op = -1`). Possible `error` values for subscribeLabels:
`FutureCursor`.
contentType: application/cbor
payload:
$ref: '#/components/schemas/ErrorFrame'
#################################################################
# Jetstream messages
#################################################################
JetstreamCommitCreate:
name: JetstreamCommitCreate
title: commit (create)
summary: |
Jetstream commit event with `commit.operation = "create"`. Contains
the full record JSON.
contentType: application/json
payload:
$ref: '#/components/schemas/JetstreamCommitCreate'
JetstreamCommitUpdate:
name: JetstreamCommitUpdate
title: commit (update)
summary: |
Jetstream commit event with `commit.operation = "update"`. Contains
the full record JSON, replacing the previous version.
contentType: application/json
payload:
$ref: '#/components/schemas/JetstreamCommitUpdate'
JetstreamCommitDelete:
name: JetstreamCommitDelete
title: commit (delete)
summary: |
Jetstream commit event with `commit.operation = "delete"`. No record
body.
contentType: application/json
payload:
$ref: '#/components/schemas/JetstreamCommitDelete'
JetstreamIdentity:
name: JetstreamIdentity
title: identity
summary: |
Jetstream identity event. Wraps the AT Protocol `#identity` event in
a Jetstream envelope.
contentType: application/json
payload:
$ref: '#/components/schemas/JetstreamIdentity'
JetstreamAccount:
name: JetstreamAccount
title: account
summary: |
Jetstream account event. Wraps the AT Protocol `#account` event in a
Jetstream envelope.
contentType: application/json
payload:
$ref: '#/components/schemas/JetstreamAccount'
JetstreamSubscriberSourcedMessage:
name: JetstreamSubscriberSourcedMessage
title: SubscriberSourcedMessage
summary: |
JSON message sent from client to Jetstream server after connecting.
Currently the only supported `type` is `options_update`.
contentType: application/json
payload:
$ref: '#/components/schemas/JetstreamSubscriberSourcedMessage'
schemas:
#################################################################
# Shared firehose frame primitives
#################################################################
FirehoseFrameHeader:
type: object
description: |
DAG-CBOR object that prefixes every WebSocket frame. `op = 1` for
regular messages (with `t` set to the short-form type, e.g.
`#commit`); `op = -1` for error frames (no `t`).
required: [op]
properties:
op:
type: integer
enum: [1, -1]
description: 1 = regular message; -1 = error frame.
t:
type: string
description: |
Short-form lexicon type identifier, e.g. `#commit`, `#identity`,
`#account`, `#handle`, `#migrate`, `#tombstone`, `#info`,
`#sync`, `#labels`. Required when `op = 1`.
ErrorFrame:
type: object
description: |
Payload of an error frame. The connection is closed by the server
immediately after the frame is sent.
required: [error]
properties:
error:
type: string
description: Short error name.
message:
type: string
description: Optional human-readable error message.
InfoFrame:
type: object
description: |
Informational message payload. Not persisted; has no `seq`.
required: [name]
properties:
name:
type: string
enum: [OutdatedCursor]
description: Short info name. Known values - `OutdatedCursor`.
message:
type: string
description: Optional human-readable message.
#################################################################
# com.atproto.sync.subscribeRepos payload schemas
#################################################################
RepoCommitFrame:
type: object
description: |
`#commit` payload. Represents an update of repository state. Empty
commits (no record changes, only `rev`/signature update) are allowed.
required:
- seq
- rebase
- tooBig
- repo
- commit
- rev
- since
- blocks
- ops
- blobs
- time
properties:
seq:
type: integer
format: int64
description: The stream sequence number of this message.
rebase:
type: boolean
description: DEPRECATED - unused.
tooBig:
type: boolean
description: |
DEPRECATED - replaced by `#sync` event and data limits. Indicates
this commit contained too many ops or was too large; consumers
need a separate fetch to recover.
repo:
type: string
format: did
description: |
The repo this event comes from. (All other message types use
`did` for the same purpose.)
commit:
type: string
format: cid
description: Repo commit object CID.
rev:
type: string
format: tid
description: |
The rev of the emitted commit. Also present inside the commit
block in `blocks` (unless `tooBig`).
since:
type: string
format: tid
nullable: true
description: The rev of the last emitted commit from this repo (if any).
blocks:
type: string
format: byte
description: |
CAR file (binary) containing relevant blocks as a diff since the
previous repo state. The commit block must be the first entry in
the CAR header `roots` list. Maximum 2,000,000 bytes.
maxLength: 2000000
ops:
type: array
maxItems: 200
description: Repo mutation operations included in this commit.
items:
$ref: '#/components/schemas/RepoOp'
blobs:
type: array
description: |
DEPRECATED - will soon always be empty. List of new blob CIDs
referenced by records in this commit.
items:
type: string
format: cid
prevData:
type: string
format: cid
description: |
Root CID of the MST tree for the previous commit (the `since`
revision). Required for the Sync 1.1 / "inductive" firehose.
time:
type: string
format: date-time
description: Timestamp of when this message was originally broadcast.
RepoOp:
type: object
description: A repo operation - a mutation of a single record.
required: [action, path, cid]
properties:
action:
type: string
enum: [create, update, delete]
path:
type: string
description: '`{collection}/{rkey}` path of the affected record.'
cid:
type: string
format: cid
nullable: true
description: |
For creates and updates, the new record CID. For deletions, null.
prev:
type: string
format: cid
description: |
For updates and deletes, the previous record CID (required for
inductive firehose). For creates, this field is omitted.
RepoSyncFrame:
type: object
description: |
`#sync` payload. Updates the repo to a new state without including the
diff on the firehose. Used to recover from broken commit streams or
data-loss incidents.
required: [seq, did, blocks, rev, time]
properties:
seq:
type: integer
format: int64
did:
type: string
format: did
description: |
The account this repo event corresponds to. Must match the value
inside the commit object.
blocks:
type: string
format: byte
description: |
CAR file (binary) containing the commit, as a block. CAR header's
first root must be the commit block CID. Maximum 10,000 bytes.
maxLength: 10000
rev:
type: string
description: |
The rev of the commit. Must match the value inside the commit
object.
time:
type: string
format: date-time
RepoIdentityFrame:
type: object
description: |
`#identity` payload. Signals that an account's identity may have
changed (handle, signing key, or PDS endpoint). Downstream services
should refresh their identity cache.
required: [seq, did, time]
properties:
seq:
type: integer
format: int64
did:
type: string
format: did
time:
type: string
format: date-time
handle:
type: string
format: handle
description: |
Current handle for the account, or `handle.invalid` if validation
fails. Optional; presence or absence does NOT indicate that the
handle itself changed.
RepoAccountFrame:
type: object
description: |
`#account` payload. Signals an account-status change on the emitting
host (PDS or Relay). The status reflects the host that emitted the
event, which may differ from the currently active PDS.
required: [seq, did, time, active]
properties:
seq:
type: integer
format: int64
did:
type: string
format: did
time:
type: string
format: date-time
active:
type: boolean
description: |
True if the host can still serve the account's repository.
status:
type: string
enum:
- takendown
- suspended
- deleted
- deactivated
- desynchronized
- throttled
description: |
If `active = false`, optionally indicates why the account is not
active.
RepoHandleFrame:
type: object
description: DEPRECATED - use `#identity` instead. Legacy handle event.
required: [seq, did, handle, time]
properties:
seq:
type: integer
format: int64
did:
type: string
format: did
handle:
type: string
format: handle
time:
type: string
format: date-time
RepoMigrateFrame:
type: object
description: DEPRECATED - use `#account` instead. Legacy migrate event.
required: [seq, did, migrateTo, time]
properties:
seq:
type: integer
format: int64
did:
type: string
format: did
migrateTo:
type: string
nullable: true
time:
type: string
format: date-time
RepoTombstoneFrame:
type: object
description: DEPRECATED - use `#account` instead. Legacy tombstone event.
required: [seq, did, time]
properties:
seq:
type: integer
format: int64
did:
type: string
format: did
time:
type: string
format: date-time
#################################################################
# com.atproto.label.subscribeLabels payload schemas
#################################################################
LabelsFrame:
type: object
description: '`#labels` payload - a batch of labels and/or negations.'
required: [seq, labels]
properties:
seq:
type: integer
format: int64
labels:
type: array
items:
$ref: '#/components/schemas/Label'
Label:
type: object
description: |
Metadata tag on an atproto resource (eg, repo or record). Defined by
`com.atproto.label.defs#label`.
required: [src, uri, val, cts]
properties:
ver:
type: integer
description: The AT Protocol version of the label object.
src:
type: string
format: did
description: DID of the actor who created this label.
uri:
type: string
format: uri
description: |
AT URI of the record, repository (account), or other resource
this label applies to.
cid:
type: string
format: cid
description: |
Optional; CID of the specific version of the `uri` resource this
label applies to.
val:
type: string
maxLength: 128
description: Short string name of the value/type of this label.
neg:
type: boolean
description: |
If true, this is a negation label that overrides a previous
label.
cts:
type: string
format: date-time
description: Timestamp when this label was created.
exp:
type: string
format: date-time
description: |
Timestamp at which this label expires (no longer applies).
sig:
type: string
format: byte
description: Signature of the dag-cbor encoded label.
#################################################################
# Jetstream payload schemas
#################################################################
JetstreamEventBase:
type: object
description: Fields present on every Jetstream event.
required: [did, time_us, kind]
properties:
did:
type: string
format: did
description: DID of the repository that produced the event.
time_us:
type: integer
format: int64
description: |
Unix microseconds timestamp at which Jetstream processed the
event. Also the cursor value to resume from.
kind:
type: string
enum: [commit, identity, account]
JetstreamCommitBase:
allOf:
- $ref: '#/components/schemas/JetstreamEventBase'
- type: object
required: [commit]
properties:
kind:
type: string
enum: [commit]
JetstreamCommitCreate:
allOf:
- $ref: '#/components/schemas/JetstreamCommitBase'
- type: object
properties:
commit:
type: object
required: [rev, operation, collection, rkey, record, cid]
properties:
rev:
type: string
format: tid
operation:
type: string
enum: [create]
collection:
type: string
description: NSID of the record's collection.
rkey:
type: string
description: Record key.
record:
type: object
description: |
Full record contents as JSON. Schema depends on the
`collection` NSID (e.g. `app.bsky.feed.post`,
`app.bsky.feed.like`, `app.bsky.graph.follow`).
cid:
type: string
format: cid
JetstreamCommitUpdate:
allOf:
- $ref: '#/components/schemas/JetstreamCommitBase'
- type: object
properties:
commit:
type: object
required: [rev, operation, collection, rkey, record, cid]
properties:
rev:
type: string
format: tid
operation:
type: string
enum: [update]
collection:
type: string
rkey:
type: string
record:
type: object
description: New full record contents, replacing the prior version.
cid:
type: string
format: cid
JetstreamCommitDelete:
allOf:
- $ref: '#/components/schemas/JetstreamCommitBase'
- type: object
properties:
commit:
type: object
required: [rev, operation, collection, rkey]
properties:
rev:
type: string
format: tid
operation:
type: string
enum: [delete]
collection:
type: string
rkey:
type: string
JetstreamIdentity:
allOf:
- $ref: '#/components/schemas/JetstreamEventBase'
- type: object
required: [identity]
properties:
kind:
type: string
enum: [identity]
identity:
type: object
description: |
Embedded AT Protocol `#identity` event. Fields mirror the
`com.atproto.sync.subscribeRepos#identity` payload.
required: [did, seq, time]
properties:
did:
type: string
format: did
handle:
type: string
format: handle
seq:
type: integer
format: int64
time:
type: string
format: date-time
JetstreamAccount:
allOf:
- $ref: '#/components/schemas/JetstreamEventBase'
- type: object
required: [account]
properties:
kind:
type: string
enum: [account]
account:
type: object
description: |
Embedded AT Protocol `#account` event. Fields mirror the
`com.atproto.sync.subscribeRepos#account` payload.
required: [active, did, seq, time]
properties:
active:
type: boolean
did:
type: string
format: did
seq:
type: integer
format: int64
time:
type: string
format: date-time
status:
type: string
enum:
- takendown
- suspended
- deleted
- deactivated
- desynchronized
- throttled
JetstreamSubscriberSourcedMessage:
type: object
description: |
Message sent from a Jetstream client to the server after connecting,
used to update subscription options on the fly. Maximum 10 MB per
message; payload limits - 100 collections and 10,000 DIDs.
required: [type, payload]
properties:
type:
type: string
enum: [options_update]
payload:
type: object
properties:
wantedCollections:
type: array
items:
type: string
wantedDids:
type: array
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bluesky/refs/heads/main/asyncapi/bluesky-asyncapi.yml