{% extends "base.html.j2" %}
{% import "try-it-macros.html.j2" as try_it %}

{% block title %}Hello!{% endblock %}
{% block body_classes %}home{% endblock %}

{% block content %}

  <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>

  <ul>
    <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>
    <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>
    <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>
    <li><a href="/links/all?target=did:plc:vc7f4oafdgxsihk4cry2xpze">What are <em>all</em> the sources of links to an identity?</a></li>
    <li>and more</li>
  </ul>

  <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>

  <p>
    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">
    {%- if let Some(days) = days_indexed %}
      {{ days|human_number }}
    {% else %}
      ???
    {% endif -%}
    </span> days.<br/>
    <small>(indexing new records in real time, backfill coming soon!)</small>
  </p>

  {# {% for k, v in stats.other_data.iter() %}
    <p><strong>{{ k }}</strong>: {{ v }}</p>
  {% endfor %} #}

  <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>


  <h2>API Endpoints</h2>

  <h3 class="route"><code>GET /xrpc/blue.microcosm.links.getBacklinks</code></h3>

  <p>A list of records linking to any record, identity, or uri.</p>

  <h4>Query parameters:</h4>

  <ul>
    <li><p><code>subject</code>: required, must url-encode. Example: <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></p></li>
    <li><p><code>source</code>: required. Example: <code>app.bsky.feed.like:subject.uri</code></p></li>
    <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>
    <li><p><code>limit</code>: optional. Default: <code>16</code>. Maximum: <code>100</code></p></li>
    <li><p><code>reverse</code>: optional, return links in reverse order. Default: <code>false</code></p></li>
  </ul>

  <p style="margin-bottom: 0"><strong>Try it:</strong></p>
  {% call
  try_it::get_backlinks("at://did:plc:a4pqq234yw7fqbddawjo7y35/app.bsky.feed.post/3m237ilwc372e", "app.bsky.feed.like:subject.uri", [""], 16, false) %}


  <h3 class="route"><code>GET /xrpc/blue.microcosm.links.getManyToManyCounts</code></h3>

  <p>TODO: description</p>

  <h4>Query parameters:</h4>

  <ul>
    <li><p><code>subject</code>: required, must url-encode. Example: <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></p></li>
    <li><p><code>source</code>: required. Example: <code>app.bsky.feed.like:subject.uri</code></p></li>
    <li><p><code>pathToOther</code>: required. Path to the secondary link in the many-to-many record. Example: <code>otherThing.uri</code></p></li>
    <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>
    <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>
    <li><p><code>limit</code>: optional. Default: <code>16</code>. Maximum: <code>100</code></p></li>
  </ul>

  <p style="margin-bottom: 0"><strong>Try it:</strong></p>
  {% call try_it::get_many_to_many_counts(
    "at://did:plc:wshs7t2adsemcrrd4snkeqli/sh.tangled.label.definition/good-first-issue",
    "sh.tangled.label.op:add[].key",
    "subject",
    [""],
    [""],
    25,
  ) %}

  <h3 class="route"><code>GET /xrpc/blue.microcosm.links.getManyToMany</code></h3>

  <p>A list of many-to-many join records linking to a target and a secondary target.</p>

  <h4>Query parameters:</h4>

  <ul>
    <li><p><code>subject</code>: required, must url-encode. Example: <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></p></li>
    <li><p><code>source</code>: required. Example: <code>app.bsky.feed.like:subject.uri</code></p></li>
    <li><p><code>pathToOther</code>: required. Path to the secondary link in the many-to-many record. Example: <code>otherThing.uri</code></p></li>
    <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>
    <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>
    <li><p><code>limit</code>: optional. Default: <code>16</code>. Maximum: <code>100</code></p></li>
  </ul>

  <p style="margin-bottom: 0"><strong>Try it:</strong></p>
  {% call try_it::get_many_to_many(
    "at://did:plc:uyauirpjzk6le4ygqzatcwnq/app.bsky.graph.list/3lzhg33t5bf2h",
    "app.bsky.graph.listitem:list",
    "subject",
    [""],
    [""],
    16,
  ) %}

  <h3 class="route"><code>GET /xrpc/blue.microcosm.links.getDistinct</code></h3>

  <p>A list of distinct DIDs (identities) with links to a target.</p>

  <h4>Query parameters:</h4>

  <ul>
    <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>
    <li><code>source</code>: required. Collection and path specification for the primary link. Example: <code>app.bsky.feed.like:subject.uri</code></li>
    <li><code>limit</code>: optional. Number of results to return. Default: <code>16</code>. Maximum: <code>100</code></li>
    <li><code>cursor</code>: optional, see Definitions.</li>
  </ul>

  <p style="margin-bottom: 0"><strong>Try it:</strong></p>
  {% call try_it::get_backlink_dids("at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r", "app.bsky.feed.like:subject.uri") %}

  <h3 class="route"><code>GET /links</code></h3>

  <p>A list of records linking to a target.</p>

  <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>

  <h4>Query parameters:</h4>

  <ul>
    <li><p><code>target</code>: required, must url-encode. Example: <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></p></li>
    <li><p><code>collection</code>: required. Example: <code>app.bsky.feed.like</code></p></li>
    <li><p><code>path</code>: required, must url-encode. Example: <code>.subject.uri</code></p></li>
    <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>
    <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>
    <li><p><code>limit</code>: optional. Default: <code>16</code>. Maximum: <code>100</code></p></li>
    <li><p><code>reverse</code>: optional, return links in reverse order. Default: <code>false</code></p></li>
  </ul>

  <p style="margin-bottom: 0"><strong>Try it:</strong></p>
  {% call try_it::links("at://did:plc:a4pqq234yw7fqbddawjo7y35/app.bsky.feed.post/3m237ilwc372e", "app.bsky.feed.like", ".subject.uri", [""], 16) %}

  <h3 class="route"><code>GET /links/distinct-dids</code></h3>

  <p>A list of distinct DIDs (identities) with links to a target.</p>

  <h4>Query parameters:</h4>

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

  <p style="margin-bottom: 0"><strong>Try it:</strong></p>
  {% call try_it::dids("at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r", "app.bsky.feed.like", ".subject.uri") %}


  <h3 class="route deprecated"><code>[deprecated] GET /links/count</code></h3>

  <p>The total number of links pointing at a given target.</p>

  <h4>Query parameters:</h4>

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

  <p style="margin-bottom: 0"><strong>Try it:</strong></p>
  {% call try_it::links_count("did:plc:vc7f4oafdgxsihk4cry2xpze", "app.bsky.graph.block", ".subject") %}

  <h3 class="route"><code>GET /xrpc/blue.microcosm.links.getBacklinksCount</code></h3>

  <p>The total number of links pointing at a given target.</p>

  <h4>Query parameters:</h4>

  <ul>
    <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>
    <li><code>source</code>: required. Collection and path specification for the primary link. Example: <code>app.bsky.feed.like:subject.uri</code></li>
  </ul>

  <p style="margin-bottom: 0"><strong>Try it:</strong></p>
  {% call try_it::get_backlinks_count("did:plc:vc7f4oafdgxsihk4cry2xpze", "app.bsky.graph.block:subject") %}

  <h3 class="route"><code>GET /links/count/distinct-dids</code></h3>

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

  <h4>Query parameters:</h4>

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

  <p style="margin-bottom: 0"><strong>Try it:</strong></p>
  {% call try_it::dids_count("did:plc:vc7f4oafdgxsihk4cry2xpze", "app.bsky.graph.block", ".subject") %}


  <h3 class="route"><code>GET /links/all</code></h3>

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

  <h4>Query parameters:</h4>

  <ul>
    <li><code>target</code>: required, must url-encode. Example: <code>did:plc:oky5czdrnfjpqslsw2a5iclo</code></li>
  </ul>

  <p style="margin-bottom: 0"><strong>Try it:</strong></p>
  {% call try_it::explore_links("did:plc:oky5czdrnfjpqslsw2a5iclo") %}


  <h3 class="route deprecated"><code>[deprecated] GET /links/all/count</code></h3>

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

  <p>DEPRECATED: Use <code>GET /links/all</code> instead.</p>

  <h4>Query parameters:</h4>

  <ul>
    <li><code>target</code>: required, must url-encode. Example: <code>did:plc:oky5czdrnfjpqslsw2a5iclo</code></li>
  </ul>

  <p style="margin-bottom: 0"><strong>Try it:</strong></p>
  {% call try_it::links_all_count("did:plc:oky5czdrnfjpqslsw2a5iclo") %}


  <h2>Definitions</h2>

  <h3>Target</h3>

  <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>

  <h3>Collection</h3>

  <p>A record NSID like <code>app.bsky.feed.like</code>.</p>

  <h3>Path</h3>

  <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>

  <h3>Cursor</h3>

  <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=&lt;cursor&gt;</code> in the URL query to get the next set of responses.</p>


{% endblock %}