This is a constellation 🌌 API server from microcosm ✨

Constellation is a self-hosted JSON API to an atproto-wide index of PDS record back-links, so you can query social interactions in real time. It can answer questions like:

It works by recursively walking all records coming through the firehose, searching for anything that looks like a link. Links are indexed by the target they point at, the collection the record came from, and the JSON path to the link in that record.

This server has indexed 9,966,933,983 links between 1,932,051,133 targets and sources from 21,108,853 identities over 4 days.
(indexing new records in real time, backfill coming soon!)

You're welcome to use this public instance! Please do not build the torment nexus. If you want to be nice, put your project name and bsky username (or email) in your user-agent header for api requests.

API Endpoints

`GET /xrpc/blue.microcosm.links.getBacklinks`

A list of records linking to any record, identity, or uri.

Query parameters:

subject: required, must url-encode. Example: at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r
source: required. Example: app.bsky.feed.like:subject.uri
did: optional, filter links to those from specific users. Include multiple times to filter by multiple users. Example: did=did:plc:vc7f4oafdgxsihk4cry2xpze&did=did:plc:vc7f4oafdgxsihk4cry2xpze
limit: optional. Default: 16. Maximum: 100

Try it:

GET /xrpc/blue.microcosm.links.getBacklinks
  ?subject=    
  &source=     
               
  &limit=

`GET /xrpc/blue.microcosm.links.getManyToManyCounts`

TODO: description

Query parameters:

subject: required, must url-encode. Example: at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r
source: required. Example: app.bsky.feed.like:subject.uri
pathToOther: required. Path to the secondary link in the many-to-many record. Example: otherThing.uri
did: optional, filter links to those from specific users. Include multiple times to filter by multiple users. Example: did=did:plc:vc7f4oafdgxsihk4cry2xpze&did=did:plc:vc7f4oafdgxsihk4cry2xpze
otherSubject: optional, filter secondary links to specific subjects. Include multiple times to filter by multiple users. Example: at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r
limit: optional. Default: 16. Maximum: 100

Try it:

GET /xrpc/blue.microcosm.links.getManyToManyCounts
  ?subject=      
  &source=       
  &pathToOther=  
                 
                 
  &limit=

`GET /links`

A list of records linking to a target.

[DEPRECATED]: use GET /xrpc/blue.microcosm.links.getBacklinks. New apps should avoid it, but this endpoint will remain supported for the forseeable future.

Query parameters:

target: required, must url-encode. Example: at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r
collection: required. Example: app.bsky.feed.like
path: required, must url-encode. Example: .subject.uri
did: optional, filter links to those from specific users. Include multiple times to filter by multiple users. Example: did=did:plc:vc7f4oafdgxsihk4cry2xpze&did=did:plc:vc7f4oafdgxsihk4cry2xpze
from_dids [deprecated]: optional. Use did instead. Example: from_dids=did:plc:vc7f4oafdgxsihk4cry2xpze,did:plc:vc7f4oafdgxsihk4cry2xpze
limit: optional. Default: 16. Maximum: 100

Try it:

GET /links
  ?target=     
  &collection= 
  &path=       
               
  &limit=

`GET /links/distinct-dids`

A list of distinct DIDs (identities) with links to a target.

Query parameters:

target: required, must url-encode. Example: at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r
collection: required. Example: app.bsky.feed.like
path: required, must url-encode. Example: .subject.uri

Try it:

GET /links/distinct-dids
  ?target=     
  &collection= 
  &path=

`GET /links/count`

The total number of links pointing at a given target.

Query parameters:

target: required, must url-encode. Example: did:plc:vc7f4oafdgxsihk4cry2xpze
collection: required. Example: app.bsky.graph.block
path: required, must url-encode. Example: .subject
cursor: optional, see Definitions.

Try it:

GET /links/count
  ?target=     
  &collection= 
  &path=

`GET /links/count/distinct-dids`

The total number of DIDs (identities) with links to at a given target.

Query parameters:

target: required, must url-encode. Example: did:plc:vc7f4oafdgxsihk4cry2xpze
collection: required. Example: app.bsky.graph.block
path: required, must url-encode. Example: .subject
cursor: optional, see Definitions.

Try it:

GET /links/count/distinct-dids
  ?target=     
  &collection= 
  &path=

`GET /links/all`

Show all sources with links to a target, including linking record counts and distinct linking DIDs

Query parameters:

target: required, must url-encode. Example: did:plc:oky5czdrnfjpqslsw2a5iclo

Try it:

GET /links/all?target=

`[deprecated] GET /links/all/count`

The total counts of all links pointing at a given target, by collection and path.

DEPRECATED: Use GET /links/all instead.

Query parameters:

target: required, must url-encode. Example: did:plc:oky5czdrnfjpqslsw2a5iclo

Try it:

GET /links/all/count?target=

Definitions

Target

A DID like did:plc:hdhoaan3xa3jiuq4fg4mefid, or an AT-URI like at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3lgu4lg6j2k2v, or a URI like https://example.com.

Collection

A record NSID like app.bsky.feed.like.

Path

A (currently-very-very-hacky) json-path-ish representation of the source of a link in a record. Records may contain multiple links with different meanings, so this specifies which specific link is of interest. Like .subject.uri.

Cursor

Paged responses include a cursor property. When it's null, no more data is available. If it's not null, you can repeat the request with &cursor=<cursor> in the URL query to get the next set of responses.