app.bsky.feed - AT Protocol

Overview

The app.bsky.feed namespace provides lexicons for posts, feeds, likes, reposts, and other feed-related functionality in Bluesky.

Key Concepts

Post: A message or content shared by a user
Feed: A chronological stream of posts
Feed Generator: Custom algorithmic feed
Interactions: Likes, reposts, replies, quotes
Thread: Conversation chain of posts

Record Types

post

A Bluesky post record. Record Structure:

string

required

Post content (max 300 graphemes, 3000 bytes)

array

Rich text annotations (mentions, links, hashtags)

object

Reply reference with root and parent

union

Embedded content (images, video, external link, record, record with media)

array

Language codes (max 3)

union

Self-applied content labels

array

Additional hashtags (max 8)

string

required

ISO 8601 timestamp

Example:

await agent.post({
  text: 'Hello Bluesky! 👋',
  createdAt: new Date().toISOString()
})

With Images:

const imageBlob = await agent.uploadBlob(imageFile, {
  encoding: 'image/jpeg'
})

await agent.post({
  text: 'Check out this sunset!',
  embed: {
    $type: 'app.bsky.embed.images',
    images: [
      {
        image: imageBlob.data.blob,
        alt: 'Beautiful orange and pink sunset over mountains'
      }
    ]
  }
})

Reply to Post:

await agent.post({
  text: 'Great point!',
  reply: {
    root: { uri: rootPostUri, cid: rootPostCid },
    parent: { uri: parentPostUri, cid: parentPostCid }
  }
})

like

Like record for a post.

ref

required

Strong reference to the liked post

string

required

Timestamp

Example:

await agent.like(postUri, postCid)

// Or manually:
await agent.com.atproto.repo.createRecord({
  repo: agent.session.did,
  collection: 'app.bsky.feed.like',
  record: {
    $type: 'app.bsky.feed.like',
    subject: { uri: postUri, cid: postCid },
    createdAt: new Date().toISOString()
  }
})

repost

Repost record.

ref

required

Strong reference to the reposted post

string

required

Timestamp

Example:

await agent.repost(postUri, postCid)

threadgate

Thread interaction rules (who can reply).

string

required

AT-URI of the post

array

Rules defining who can reply (mentions, followers, following, lists)

string

required

Timestamp

postgate

Post embedding rules.

string

required

AT-URI of the post

array

Rules for embedding (can disable embedding)

string

required

Timestamp

generator

Feed generator declaration.

string

required

DID of the feed generator service

string

required

Feed name

string

Feed description (max 300 graphemes)

blob

Feed avatar image

boolean

Whether feed accepts interaction data

union

Self-applied labels

string

required

Timestamp

Queries

getTimeline

Get the authenticated user’s home timeline. Endpoint: app.bsky.feed.getTimeline Authentication: Required

string

Timeline algorithm variant

integer

Max posts (1-100, default 50)

string

Pagination cursor

Response:

string

Next page cursor

array

required

Array of feed view posts

Example:

const response = await agent.getTimeline({
  limit: 30
})

for (const item of response.data.feed) {
  console.log(item.post.author.handle, item.post.record.text)
}

getAuthorFeed

Get posts by a specific author. Endpoint: app.bsky.feed.getAuthorFeed

string

required

Handle or DID

integer

Max posts (1-100, default 50)

string

Pagination cursor

string

Filter: posts_with_replies, posts_no_replies, posts_with_media, posts_and_author_threads

Example:

const response = await agent.getAuthorFeed({
  actor: 'alice.bsky.social',
  filter: 'posts_no_replies'
})

getFeed

Get posts from a feed generator. Endpoint: app.bsky.feed.getFeed

string

required

AT-URI of the feed generator

integer

Max posts (1-100, default 50)

string

Pagination cursor

Example:

const response = await agent.app.bsky.feed.getFeed({
  feed: 'at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.generator/whats-hot'
})

getPosts

Get hydrated post views for specific posts. Endpoint: app.bsky.feed.getPosts

array

required

Array of post AT-URIs (max 25)

Response:

array

required

Array of post views

Example:

const response = await agent.app.bsky.feed.getPosts({
  uris: [
    'at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3k2y...',
    'at://did:plc:abc123/app.bsky.feed.post/3k3z...'
  ]
})

for (const post of response.data.posts) {
  console.log(post.record.text)
}

getPostThread

Get a post and its thread context. Endpoint: app.bsky.feed.getPostThread

string

required

AT-URI of the post

integer

How many levels of reply depth to fetch (default 6, max 1000)

integer

How many levels of parent posts to fetch (default 80, max 1000)

Response: Thread view with post, parent, and replies Example:

const response = await agent.getPostThread(postUri)

const thread = response.data.thread
console.log('Post:', thread.post.record.text)
console.log('Replies:', thread.replies?.length)

getLikes

Get likes for a post. Endpoint: app.bsky.feed.getLikes

string

required

AT-URI of the post

integer

Max likes (1-100, default 50)

string

Pagination cursor

Response: Array of likes with actor profiles

getRepostedBy

Get reposts for a post. Endpoint: app.bsky.feed.getRepostedBy

string

required

AT-URI of the post

integer

Max reposts (1-100, default 50)

string

Pagination cursor

Response: Array of actors who reposted

getQuotes

Get quote posts of a post. Endpoint: app.bsky.feed.getQuotes

string

required

AT-URI of the post

integer

Max quotes (1-100, default 50)

string

Pagination cursor

searchPosts

Search for posts. Endpoint: app.bsky.feed.searchPosts

string

required

Search query

integer

Max results (1-100, default 25)

string

Pagination cursor

string

Filter by author

string

Filter by date (ISO 8601)

string

Filter by date (ISO 8601)

string

Filter by mentioned user

string

Filter by language

string

Filter by domain in links

string

Filter by URL in links

array

Filter by hashtags

Example:

const response = await agent.app.bsky.feed.searchPosts({
  q: 'atproto',
  limit: 20,
  lang: 'en'
})

Feed Generators

getFeedGenerator

Get information about a feed generator. Endpoint: app.bsky.feed.getFeedGenerator

string

required

AT-URI of the feed generator

getFeedGenerators

Get information about multiple feed generators. Endpoint: app.bsky.feed.getFeedGenerators

array

required

Array of feed generator AT-URIs

getSuggestedFeeds

Get suggested feed generators. Endpoint: app.bsky.feed.getSuggestedFeeds

integer

Max feeds (1-100, default 50)

string

Pagination cursor

getActorFeeds

Get feed generators created by an actor. Endpoint: app.bsky.feed.getActorFeeds

string

required

Handle or DID

integer

Max feeds (1-100, default 50)

string

Pagination cursor

getActorLikes

Get posts liked by an actor. Endpoint: app.bsky.feed.getActorLikes

string

required

Handle or DID

integer

Max posts (1-100, default 50)

string

Pagination cursor

getListFeed

Get posts from a list. Endpoint: app.bsky.feed.getListFeed

string

required

AT-URI of the list

integer

Max posts (1-100, default 50)

string

Pagination cursor

Procedures

sendInteractions

Send interaction events to feed generators. Endpoint: app.bsky.feed.sendInteractions Authentication: Required

array

required

Array of interaction events

Type Definitions

postView

Complete post view with engagement metrics.

string

required

Post AT-URI

string

required

Post CID

object

required

Author profile

object

required

Post record data

union

Embedded content view

integer

Number of replies

integer

Number of reposts

integer

Number of likes

integer

Number of quote posts

string

required

Indexing timestamp

object

Viewer’s interaction state

array

Content labels

Common Use Cases

Create a Post with Mentions

import { RichText } from '@atproto/api'

const rt = new RichText({ text: 'Hello @alice.bsky.social!' })
await rt.detectFacets(agent)

await agent.post({
  text: rt.text,
  facets: rt.facets
})

Create Thread

// First post
const post1 = await agent.post({
  text: '1/ Here’s a thread about AT Protocol...'
})

// Reply to create thread
const post2 = await agent.post({
  text: '2/ The AT Protocol is designed to be decentralized...',
  reply: {
    root: { uri: post1.uri, cid: post1.cid },
    parent: { uri: post1.uri, cid: post1.cid }
  }
})

const post3 = await agent.post({
  text: '3/ It uses content-addressed storage...',
  reply: {
    root: { uri: post1.uri, cid: post1.cid },
    parent: { uri: post2.uri, cid: post2.cid }
  }
})

Quote Post

await agent.post({
  text: 'Great insight!',
  embed: {
    $type: 'app.bsky.embed.record',
    record: {
      uri: quotedPostUri,
      cid: quotedPostCid
    }
  }
})

app.bsky.actor - User profiles
app.bsky.graph - Social graph
app.bsky.embed - Embeds
app.bsky.richtext - Rich text

​Overview

​Key Concepts

​Record Types

​post

​like

​repost

​threadgate

​postgate

​generator

​Queries

​getTimeline

​getAuthorFeed

​getFeed

​getPosts

​getPostThread

​getLikes

​getRepostedBy

​getQuotes

​searchPosts

​Feed Generators

​getFeedGenerator

​getFeedGenerators

​getSuggestedFeeds

​getActorFeeds

​getActorLikes

​getListFeed

​Procedures

​sendInteractions

​Type Definitions

​postView

​Common Use Cases

​Create a Post with Mentions

​Create Thread

​Quote Post

​Related Lexicons

​Resources

Overview

Key Concepts

Record Types

post

like

repost

threadgate

postgate

generator

Queries

getTimeline

getAuthorFeed

getFeed

getPosts

getPostThread

getLikes

getRepostedBy

getQuotes

searchPosts

Feed Generators

getFeedGenerator

getFeedGenerators

getSuggestedFeeds

getActorFeeds

getActorLikes

getListFeed

Procedures

sendInteractions

Type Definitions

postView

Common Use Cases

Create a Post with Mentions

Create Thread

Quote Post

Related Lexicons

Resources