docs / bluesky

Bluesky

Profiles, posts, followers and the social graph.

base /bluesky/v113 endpoints

post/bluesky/v1/profile1 credit

actor profile: did/handle/displayName/desc/followers/follows/posts counts/avatar/banner/labels (+ batch via 'actors' <=25). Requires actor OR actors (engine-enforced; required_params=() so the actors-only batch isn't rejected by the gateway literal-key validator).

Parameter		Allowed / range	Description
actor	optional	—	A Bluesky account — its handle (e.g. bsky.app), a did:plc:… DID, or a bsky.app/profile/<…> URL. The AppView resolves all three.
actors	optional	—	Batch mode: up to 25 handles/DIDs (array or comma-separated string). When given, returns a profiles[] batch instead of a single profile.

Try in playground →

post/bluesky/v1/author_feed1 credit

an actor's posts (full record+embed+counts), cursor-paginated; filter=posts_no_replies|posts_with_replies|posts_with_media|posts_and_author_threads

Parameter		Allowed / range	Description
actor	required	—	A Bluesky account — its handle (e.g. bsky.app), a did:plc:… DID, or a bsky.app/profile/<…> URL. The AppView resolves all three.
filter = posts_no_replies	optional	posts_no_replies · posts_with_replies · posts_with_media · posts_and_author_threads	Which of the author's posts to include.
limit = 30	optional	1–200	Max records to return (1-200, default 30). Auto-paginated; larger values are clamped to 200.
cursor	optional	—	Pagination cursor from a previous response's `cursor`. Omit for page one.

Try in playground →

post/bluesky/v1/search_actors1 credit

search users by name/handle/bio (cursor); typeahead=true for fast suggest

Parameter		Allowed / range	Description
q	required	—	Search query (keywords; also accepted as 'query').
typeahead	optional	—	true = fast as-you-type suggestions (no pagination); false = full search.
limit = 25	optional	1–100	Max records to return (1-100, default 25). Auto-paginated; larger values are clamped to 100.
cursor	optional	—	Pagination cursor from a previous response's `cursor`. Omit for page one.

Try in playground →

post/bluesky/v1/thread1 credit

a post + its reply tree (recursive) + parent

Parameter		Allowed / range	Description
uri	required	—	The post's at:// AT-URI (or a bsky.app/profile/<did>/post/<rkey> URL). Get it from a post's `uri` field.
depth = 6	optional	0–100	How many levels of replies to include below the post (0-100).
parent_height = 0	optional	0–100	How many parent posts above the target to include (0-100).

Try in playground →

post/bluesky/v1/post_detail1 credit

hydrate one or more posts by at:// URI (<=25): record/embed/like+repost+reply+quote counts

Parameter		Allowed / range	Description
uris	required	—	One or more post at:// AT-URIs (array or comma-separated string, up to 25). A single 'uri' is also accepted.

Try in playground →

post/bluesky/v1/likes1 credit

actors who liked a post (cursor); cid auto-used if given

Parameter		Allowed / range	Description
uri	required	—	The post's at:// AT-URI (or a bsky.app/profile/<did>/post/<rkey> URL). Get it from a post's `uri` field.
cid	optional	—	Optional post content-id (a post's `cid`). Speeds up the lookup; auto-resolved from the URI when omitted.
limit = 50	optional	1–500	Max records to return (1-500, default 50). Auto-paginated; larger values are clamped to 500.
cursor	optional	—	Pagination cursor from a previous response's `cursor`. Omit for page one.

Try in playground →

post/bluesky/v1/reposts1 credit

actors who reposted a post (cursor)

Parameter		Allowed / range	Description
uri	required	—	The post's at:// AT-URI (or a bsky.app/profile/<did>/post/<rkey> URL). Get it from a post's `uri` field.
cid	optional	—	Optional post content-id (a post's `cid`). Speeds up the lookup; auto-resolved from the URI when omitted.
limit = 50	optional	1–500	Max records to return (1-500, default 50). Auto-paginated; larger values are clamped to 500.
cursor	optional	—	Pagination cursor from a previous response's `cursor`. Omit for page one.

Try in playground →

post/bluesky/v1/followers1 credit

actors following the subject (cursor)

Parameter		Allowed / range	Description
actor	required	—	A Bluesky account — its handle (e.g. bsky.app), a did:plc:… DID, or a bsky.app/profile/<…> URL. The AppView resolves all three.
limit = 100	optional	1–2000	Max records to return (1-2000, default 100). Auto-paginated; larger values are clamped to 2000.
cursor	optional	—	Pagination cursor from a previous response's `cursor`. Omit for page one.

Try in playground →

post/bluesky/v1/follows1 credit

actors the subject follows (cursor)

Parameter		Allowed / range	Description
actor	required	—	A Bluesky account — its handle (e.g. bsky.app), a did:plc:… DID, or a bsky.app/profile/<…> URL. The AppView resolves all three.
limit = 100	optional	1–2000	Max records to return (1-2000, default 100). Auto-paginated; larger values are clamped to 2000.
cursor	optional	—	Pagination cursor from a previous response's `cursor`. Omit for page one.

Try in playground →

post/bluesky/v1/search_posts1 credit

Search Bluesky posts by keyword or hashtag — filter by sort order, date range, author, language, domain or tag. Requires an app-password; returns a clear error if none is configured.

Parameter		Allowed / range	Description
q	required	—	Search query (keywords; also accepted as 'query').
sort = top	optional	top · latest	Result ordering for post search.
limit = 25	optional	1–100	Max records to return (1-100, default 25). Auto-paginated; larger values are clamped to 100.
cursor	optional	—	Pagination cursor from a previous response's `cursor`. Omit for page one.
since	optional	—	Only posts at/after this time (ISO-8601 or YYYY-MM-DD).
until	optional	—	Only posts at/before this time (ISO-8601 or YYYY-MM-DD).
author	optional	—	Restrict to posts by this account (handle or DID).
mentions	optional	—	Restrict to posts mentioning this account (handle or DID).
lang	optional	—	Restrict to posts in this language (BCP-47 code, e.g. en, tr, ja).
domain	optional	—	Restrict to posts linking to this domain.
url	optional	—	Restrict to posts linking to this exact URL.
tag	optional	—	Restrict to posts with this hashtag (without the #).

Try in playground →

post/bluesky/v1/get_actor_likes1 credit

posts an actor liked (authed; the AppView serves the authenticated account's own likes). Defaults to the logged-in handle.

Parameter		Allowed / range	Description
actor	optional	—	A Bluesky account — its handle (e.g. bsky.app), a did:plc:… DID, or a bsky.app/profile/<…> URL. The AppView resolves all three.
limit = 30	optional	1–200	Max records to return (1-200, default 30). Auto-paginated; larger values are clamped to 200.
cursor	optional	—	Pagination cursor from a previous response's `cursor`. Omit for page one.

Try in playground →

post/bluesky/v1/timeline1 credit

the authenticated account's home timeline (authed)

Parameter		Allowed / range	Description
limit = 30	optional	1–200	Max records to return (1-200, default 30). Auto-paginated; larger values are clamped to 200.
algorithm	optional	—	Optional timeline algorithm key (server-defined; omit for the default).
cursor	optional	—	Pagination cursor from a previous response's `cursor`. Omit for page one.

Try in playground →

post/bluesky/v1/get_feed1 credit

posts from a custom feed generator by at:// URI (authed)

Parameter		Allowed / range	Description
feed	required	—	A feed-generator's at:// URI (e.g. a custom/discover feed). Get it from a profile's associated feedgens or a feed's share URL.
limit = 30	optional	1–200	Max records to return (1-200, default 30). Auto-paginated; larger values are clamped to 200.
cursor	optional	—	Pagination cursor from a previous response's `cursor`. Omit for page one.

Try in playground →

Example request · profile

curl -X POST https://api.reefapi.com/bluesky/v1/profile \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"actor":"bsky.app"}'

Response shape

{
  "ok": true,
  "data": { /* the result */ },
  "meta": {
    "latency_ms": 240,
    "record_count": 12,
    "completeness_pct": 100
  },
  "error": null
}