Constellation, Spacedust, Slingshot, UFOs: atproto crates and services for microcosm
1{% extends "base.html.j2" %}
2{% import "try-it-macros.html.j2" as try_it %}
3
4{% block title %}Hello!{% endblock %}
5{% block body_classes %}home{% endblock %}
6
7{% block content %}
8
9 <p>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:</p>
10
11 <ul>
12 <li><a href="/links/count/distinct-dids?target={{ "at://did:plc:44ybard66vv44zksje25o7dz/app.bsky.feed.post/3lhhz7k2yqk2h"|urlencode }}&collection=app.bsky.feed.like&path=.subject.uri">How many people liked a liked a bluesky post?</a></li>
13 <li><a href="/links/distinct-dids?target=did:plc:oky5czdrnfjpqslsw2a5iclo&collection=app.bsky.graph.follow&path=.subject">Who are all the bluesky followers of an identity?</a></li>
14 <li><a href="/links?target=at://did:plc:nlromb2qyyl6rszaluwhfy6j/fyi.unravel.frontpage.post/3lhd2ivyc422n&collection=fyi.unravel.frontpage.comment&path=.post.uri">What are all the replies to a Frontpage submission?</a></li>
15 <li><a href="/links/all?target=did:plc:vc7f4oafdgxsihk4cry2xpze">What are <em>all</em> the sources of links to an identity?</a></li>
16 <li>and more</li>
17 </ul>
18
19 <p>It works by recursively walking <em>all</em> 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.</p>
20
21 <p>
22 This server has indexed <span class="stat">{{ stats.linking_records|human_number }}</span> links between <span class="stat">{{ stats.targetables|human_number }}</span> targets and sources from <span class="stat">{{ stats.dids|human_number }}</span> identities over <span class="stat">
23 {%- if let Some(days) = days_indexed %}
24 {{ days|human_number }}
25 {% else %}
26 ???
27 {% endif -%}
28 </span> days.<br/>
29 <small>(indexing new records in real time, backfill coming soon!)</small>
30 </p>
31
32 {# {% for k, v in stats.other_data.iter() %}
33 <p><strong>{{ k }}</strong>: {{ v }}</p>
34 {% endfor %} #}
35
36 <p>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.</p>
37
38
39 <h2>API Endpoints</h2>
40
41 <h3 class="route"><code>GET /xrpc/blue.microcosm.links.getBacklinks</code></h3>
42
43 <p>A list of records linking to any record, identity, or uri.</p>
44
45 <h4>Query parameters:</h4>
46
47 <ul>
48 <li><p><code>subject</code>: required, must url-encode. Example: <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></p></li>
49 <li><p><code>source</code>: required. Example: <code>app.bsky.feed.like:subject.uri</code></p></li>
50 <li><p><code>did</code>: optional, filter links to those from specific users. Include multiple times to filter by multiple users. Example: <code>did=did:plc:vc7f4oafdgxsihk4cry2xpze&did=did:plc:vc7f4oafdgxsihk4cry2xpze</code></p></li>
51 <li><p><code>limit</code>: optional. Default: <code>16</code>. Maximum: <code>100</code></p></li>
52 <li><p><code>reverse</code>: optional, return links in reverse order. Default: <code>false</code></p></li>
53 </ul>
54
55 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
56 {% call
57 try_it::get_backlinks("at://did:plc:a4pqq234yw7fqbddawjo7y35/app.bsky.feed.post/3m237ilwc372e", "app.bsky.feed.like:subject.uri", [""], 16, false) %}
58
59
60 <h3 class="route"><code>GET /xrpc/blue.microcosm.links.getManyToManyCounts</code></h3>
61
62 <p>TODO: description</p>
63
64 <h4>Query parameters:</h4>
65
66 <ul>
67 <li><p><code>subject</code>: required, must url-encode. Example: <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></p></li>
68 <li><p><code>source</code>: required. Example: <code>app.bsky.feed.like:subject.uri</code></p></li>
69 <li><p><code>pathToOther</code>: required. Path to the secondary link in the many-to-many record. Example: <code>otherThing.uri</code></p></li>
70 <li><p><code>did</code>: optional, filter links to those from specific users. Include multiple times to filter by multiple users. Example: <code>did=did:plc:vc7f4oafdgxsihk4cry2xpze&did=did:plc:vc7f4oafdgxsihk4cry2xpze</code></p></li>
71 <li><p><code>otherSubject</code>: optional, filter secondary links to specific subjects. Include multiple times to filter by multiple users. Example: <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></p></li>
72 <li><p><code>limit</code>: optional. Default: <code>16</code>. Maximum: <code>100</code></p></li>
73 </ul>
74
75 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
76 {% call try_it::get_many_to_many_counts(
77 "at://did:plc:wshs7t2adsemcrrd4snkeqli/sh.tangled.label.definition/good-first-issue",
78 "sh.tangled.label.op:add[].key",
79 "subject",
80 [""],
81 [""],
82 25,
83 ) %}
84
85
86 <h3 class="route"><code>GET /links</code></h3>
87
88 <p>A list of records linking to a target.</p>
89
90 <p>[DEPRECATED]: use <code>GET /xrpc/blue.microcosm.links.getBacklinks</code>. New apps should avoid it, but this endpoint <strong>will</strong> remain supported for the forseeable future.</p>
91
92 <h4>Query parameters:</h4>
93
94 <ul>
95 <li><p><code>target</code>: required, must url-encode. Example: <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></p></li>
96 <li><p><code>collection</code>: required. Example: <code>app.bsky.feed.like</code></p></li>
97 <li><p><code>path</code>: required, must url-encode. Example: <code>.subject.uri</code></p></li>
98 <li><p><code>did</code>: optional, filter links to those from specific users. Include multiple times to filter by multiple users. Example: <code>did=did:plc:vc7f4oafdgxsihk4cry2xpze&did=did:plc:vc7f4oafdgxsihk4cry2xpze</code></p></li>
99 <li><p><code>from_dids</code> [deprecated]: optional. Use <code>did</code> instead. Example: <code>from_dids=did:plc:vc7f4oafdgxsihk4cry2xpze,did:plc:vc7f4oafdgxsihk4cry2xpze</code></p></li>
100 <li><p><code>limit</code>: optional. Default: <code>16</code>. Maximum: <code>100</code></p></li>
101 <li><p><code>reverse</code>: optional, return links in reverse order. Default: <code>false</code></p></li>
102 </ul>
103
104 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
105 {% call try_it::links("at://did:plc:a4pqq234yw7fqbddawjo7y35/app.bsky.feed.post/3m237ilwc372e", "app.bsky.feed.like", ".subject.uri", [""], 16) %}
106
107
108 <h3 class="route"><code>GET /links/distinct-dids</code></h3>
109
110 <p>A list of distinct DIDs (identities) with links to a target.</p>
111
112 <h4>Query parameters:</h4>
113
114 <ul>
115 <li><code>target</code>: required, must url-encode. Example: <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></li>
116 <li><code>collection</code>: required. Example: <code>app.bsky.feed.like</code></li>
117 <li><code>path</code>: required, must url-encode. Example: <code>.subject.uri</code></li>
118 </ul>
119
120 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
121 {% call try_it::dids("at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r", "app.bsky.feed.like", ".subject.uri") %}
122
123
124 <h3 class="route deprecated"><code>[deprecated] GET /links/count</code></h3>
125
126 <p>The total number of links pointing at a given target.</p>
127
128 <h4>Query parameters:</h4>
129
130 <ul>
131 <li><code>target</code>: required, must url-encode. Example: <code>did:plc:vc7f4oafdgxsihk4cry2xpze</code></li>
132 <li><code>collection</code>: required. Example: <code>app.bsky.graph.block</code></li>
133 <li><code>path</code>: required, must url-encode. Example: <code>.subject</code></li>
134 <li><code>cursor</code>: optional, see Definitions.</li>
135 </ul>
136
137 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
138 {% call try_it::links_count("did:plc:vc7f4oafdgxsihk4cry2xpze", "app.bsky.graph.block", ".subject") %}
139
140 <h3 class="route"><code>GET /xrpc/blue.microcosm.links.getBacklinksCount</code></h3>
141
142 <p>The total number of links pointing at a given target.</p>
143
144 <h4>Query parameters:</h4>
145
146 <ul>
147 <li><code>subject</code>: required, must url-encode. The target being linked to. Example: <code>did:plc:vc7f4oafdgxsihk4cry2xpze</code> or <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></li>
148 <li><code>source</code>: required. Collection and path specification for the primary link. Example: <code>app.bsky.feed.like:subject.uri</code></li>
149 </ul>
150
151 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
152 {% call try_it::get_backlinks_count("did:plc:vc7f4oafdgxsihk4cry2xpze", "app.bsky.graph.block:subject") %}
153
154 <h3 class="route"><code>GET /links/count/distinct-dids</code></h3>
155
156 <p>The total number of DIDs (identities) with links to at a given target.</p>
157
158 <h4>Query parameters:</h4>
159
160 <ul>
161 <li><code>target</code>: required, must url-encode. Example: <code>did:plc:vc7f4oafdgxsihk4cry2xpze</code></li>
162 <li><code>collection</code>: required. Example: <code>app.bsky.graph.block</code></li>
163 <li><code>path</code>: required, must url-encode. Example: <code>.subject</code></li>
164 <li><code>cursor</code>: optional, see Definitions.</li>
165 </ul>
166
167 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
168 {% call try_it::dids_count("did:plc:vc7f4oafdgxsihk4cry2xpze", "app.bsky.graph.block", ".subject") %}
169
170
171 <h3 class="route"><code>GET /links/all</code></h3>
172
173 <p>Show all sources with links to a target, including linking record counts and distinct linking DIDs</p>
174
175 <h4>Query parameters:</h4>
176
177 <ul>
178 <li><code>target</code>: required, must url-encode. Example: <code>did:plc:oky5czdrnfjpqslsw2a5iclo</code></li>
179 </ul>
180
181 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
182 {% call try_it::explore_links("did:plc:oky5czdrnfjpqslsw2a5iclo") %}
183
184
185 <h3 class="route deprecated"><code>[deprecated] GET /links/all/count</code></h3>
186
187 <p>The total counts of all links pointing at a given target, by collection and path.</p>
188
189 <p>DEPRECATED: Use <code>GET /links/all</code> instead.</p>
190
191 <h4>Query parameters:</h4>
192
193 <ul>
194 <li><code>target</code>: required, must url-encode. Example: <code>did:plc:oky5czdrnfjpqslsw2a5iclo</code></li>
195 </ul>
196
197 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
198 {% call try_it::links_all_count("did:plc:oky5czdrnfjpqslsw2a5iclo") %}
199
200
201 <h2>Definitions</h2>
202
203 <h3>Target</h3>
204
205 <p>A DID like <code>did:plc:hdhoaan3xa3jiuq4fg4mefid</code>, or an AT-URI like <code>at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3lgu4lg6j2k2v</code>, or a URI like <code>https://example.com</code>.</p>
206
207 <h3>Collection</h3>
208
209 <p>A record NSID like <code>app.bsky.feed.like</code>.</p>
210
211 <h3>Path</h3>
212
213 <p>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 <code>.subject.uri</code>.</p>
214
215 <h3>Cursor</h3>
216
217 <p>Paged responses include a <code>cursor</code> property. When it's <code>null</code>, no more data is available. If it's not null, you can repeat the request with <code>&cursor=<cursor></code> in the URL query to get the next set of responses.</p>
218
219
220{% endblock %}