microcosm.blue
Constellation, Spacedust, Slingshot, UFOs: atproto crates and services for microcosm
bad-example.com
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 <h3 class="route"><code>GET /xrpc/blue.microcosm.links.getManyToMany</code></h3>
86
87 <p>A list of many-to-many join records linking to a target and a secondary target.</p>
88
89 <h4>Query parameters:</h4>
90
91 <ul>
92 <li><p><code>subject</code>: required, must url-encode. Example: <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></p></li>
93 <li><p><code>source</code>: required. Example: <code>app.bsky.feed.like:subject.uri</code></p></li>
94 <li><p><code>pathToOther</code>: required. Path to the secondary link in the many-to-many record. Example: <code>otherThing.uri</code></p></li>
95 <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>
96 <li><p><code>otherSubject</code>: optional, filter secondary links to specific subjects. Include multiple times to filter by multiple subjects. Example: <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></p></li>
97 <li><p><code>limit</code>: optional. Default: <code>16</code>. Maximum: <code>100</code></p></li>
98 </ul>
99
100 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
101 {% call try_it::get_many_to_many(
102 "at://did:plc:uyauirpjzk6le4ygqzatcwnq/app.bsky.graph.list/3lzhg33t5bf2h",
103 "app.bsky.graph.listitem:list",
104 "subject",
105 [""],
106 [""],
107 16,
108 ) %}
109
110 <h3 class="route"><code>GET /xrpc/blue.microcosm.links.getDistinct</code></h3>
111
112 <p>A list of distinct DIDs (identities) with links to a target.</p>
113
114 <h4>Query parameters:</h4>
115
116 <ul>
117 <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>
118 <li><code>source</code>: required. Collection and path specification for the primary link. Example: <code>app.bsky.feed.like:subject.uri</code></li>
119 <li><code>limit</code>: optional. Number of results to return. Default: <code>16</code>. Maximum: <code>100</code></li>
120 <li><code>cursor</code>: optional, see Definitions.</li>
121 </ul>
122
123 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
124 {% call try_it::get_backlink_dids("at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r", "app.bsky.feed.like:subject.uri") %}
125
126 <h3 class="route"><code>GET /links</code></h3>
127
128 <p>A list of records linking to a target.</p>
129
130 <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>
131
132 <h4>Query parameters:</h4>
133
134 <ul>
135 <li><p><code>target</code>: required, must url-encode. Example: <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></p></li>
136 <li><p><code>collection</code>: required. Example: <code>app.bsky.feed.like</code></p></li>
137 <li><p><code>path</code>: required, must url-encode. Example: <code>.subject.uri</code></p></li>
138 <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>
139 <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>
140 <li><p><code>limit</code>: optional. Default: <code>16</code>. Maximum: <code>100</code></p></li>
141 <li><p><code>reverse</code>: optional, return links in reverse order. Default: <code>false</code></p></li>
142 </ul>
143
144 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
145 {% call try_it::links("at://did:plc:a4pqq234yw7fqbddawjo7y35/app.bsky.feed.post/3m237ilwc372e", "app.bsky.feed.like", ".subject.uri", [""], 16) %}
146
147 <h3 class="route"><code>GET /links/distinct-dids</code></h3>
148
149 <p>A list of distinct DIDs (identities) with links to a target.</p>
150
151 <h4>Query parameters:</h4>
152
153 <ul>
154 <li><code>target</code>: required, must url-encode. Example: <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></li>
155 <li><code>collection</code>: required. Example: <code>app.bsky.feed.like</code></li>
156 <li><code>path</code>: required, must url-encode. Example: <code>.subject.uri</code></li>
157 </ul>
158
159 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
160 {% call try_it::dids("at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r", "app.bsky.feed.like", ".subject.uri") %}
161
162
163 <h3 class="route deprecated"><code>[deprecated] GET /links/count</code></h3>
164
165 <p>The total number of links pointing at a given target.</p>
166
167 <h4>Query parameters:</h4>
168
169 <ul>
170 <li><code>target</code>: required, must url-encode. Example: <code>did:plc:vc7f4oafdgxsihk4cry2xpze</code></li>
171 <li><code>collection</code>: required. Example: <code>app.bsky.graph.block</code></li>
172 <li><code>path</code>: required, must url-encode. Example: <code>.subject</code></li>
173 <li><code>cursor</code>: optional, see Definitions.</li>
174 </ul>
175
176 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
177 {% call try_it::links_count("did:plc:vc7f4oafdgxsihk4cry2xpze", "app.bsky.graph.block", ".subject") %}
178
179 <h3 class="route"><code>GET /xrpc/blue.microcosm.links.getBacklinksCount</code></h3>
180
181 <p>The total number of links pointing at a given target.</p>
182
183 <h4>Query parameters:</h4>
184
185 <ul>
186 <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>
187 <li><code>source</code>: required. Collection and path specification for the primary link. Example: <code>app.bsky.feed.like:subject.uri</code></li>
188 </ul>
189
190 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
191 {% call try_it::get_backlinks_count("did:plc:vc7f4oafdgxsihk4cry2xpze", "app.bsky.graph.block:subject") %}
192
193 <h3 class="route"><code>GET /links/count/distinct-dids</code></h3>
194
195 <p>The total number of DIDs (identities) with links to at a given target.</p>
196
197 <h4>Query parameters:</h4>
198
199 <ul>
200 <li><code>target</code>: required, must url-encode. Example: <code>did:plc:vc7f4oafdgxsihk4cry2xpze</code></li>
201 <li><code>collection</code>: required. Example: <code>app.bsky.graph.block</code></li>
202 <li><code>path</code>: required, must url-encode. Example: <code>.subject</code></li>
203 <li><code>cursor</code>: optional, see Definitions.</li>
204 </ul>
205
206 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
207 {% call try_it::dids_count("did:plc:vc7f4oafdgxsihk4cry2xpze", "app.bsky.graph.block", ".subject") %}
208
209
210 <h3 class="route"><code>GET /links/all</code></h3>
211
212 <p>Show all sources with links to a target, including linking record counts and distinct linking DIDs</p>
213
214 <h4>Query parameters:</h4>
215
216 <ul>
217 <li><code>target</code>: required, must url-encode. Example: <code>did:plc:oky5czdrnfjpqslsw2a5iclo</code></li>
218 </ul>
219
220 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
221 {% call try_it::explore_links("did:plc:oky5czdrnfjpqslsw2a5iclo") %}
222
223
224 <h3 class="route deprecated"><code>[deprecated] GET /links/all/count</code></h3>
225
226 <p>The total counts of all links pointing at a given target, by collection and path.</p>
227
228 <p>DEPRECATED: Use <code>GET /links/all</code> instead.</p>
229
230 <h4>Query parameters:</h4>
231
232 <ul>
233 <li><code>target</code>: required, must url-encode. Example: <code>did:plc:oky5czdrnfjpqslsw2a5iclo</code></li>
234 </ul>
235
236 <p style="margin-bottom: 0"><strong>Try it:</strong></p>
237 {% call try_it::links_all_count("did:plc:oky5czdrnfjpqslsw2a5iclo") %}
238
239
240 <h2>Definitions</h2>
241
242 <h3>Target</h3>
243
244 <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>
245
246 <h3>Collection</h3>
247
248 <p>A record NSID like <code>app.bsky.feed.like</code>.</p>
249
250 <h3>Path</h3>
251
252 <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>
253
254 <h3>Cursor</h3>
255
256 <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>
257
258
259{% endblock %}