Something went wrong. Try again.
hardened bluesky app fork with microcosm
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575openapi: 3.1.0info: title: Constellation API version: '1.0.0' summary: atproto-wide index of PDS record back-links description: > Constellation 🌌 (from microcosm ✨) is a self-hosted JSON API to an atproto-wide index of PDS record back-links, letting you query social interactions in real time — e.g. how many people liked a post, who follows an identity, all replies to a record, or all sources linking to a URI.
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 within that record.
**Etiquette:** When using the public instance, set a `User-Agent` header that includes your project name and a contact (bsky username or email).
**Note on response schemas:** The upstream Constellation docs document request parameters and the `cursor` pagination field, but do not publish full response body schemas. The response schemas below were verified against the live public instance (June 2026). contact: name: microcosm url: https://www.microcosm.blue/ license: name: See microcosm.blue
servers: - url: https://constellation.microcosm.blue description: Public instance
tags: - name: links description: Current (XRPC, blue.microcosm.links.*) endpoints - name: legacy description: Deprecated REST endpoints — supported for the foreseeable future, but new apps should prefer the XRPC endpoints
paths: /xrpc/blue.microcosm.links.getBacklinks: get: operationId: getBacklinks tags: [links] summary: List records linking to a target description: A list of records linking to any record, identity, or URI. parameters: - $ref: '#/components/parameters/Subject' - $ref: '#/components/parameters/Source' - $ref: '#/components/parameters/DidFilter' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Reverse' - $ref: '#/components/parameters/Cursor' responses: '200': description: A page of backlink records. content: application/json: schema: $ref: '#/components/schemas/BacklinksResponse' '400': $ref: '#/components/responses/BadRequest'
/xrpc/blue.microcosm.links.getBacklinksCount: get: operationId: getBacklinksCount tags: [links] summary: Count of links pointing at a target description: The total number of links pointing at a given target. parameters: - $ref: '#/components/parameters/Subject' - $ref: '#/components/parameters/Source' responses: '200': description: The total link count. content: application/json: schema: $ref: '#/components/schemas/CountResponse' '400': $ref: '#/components/responses/BadRequest'
/xrpc/blue.microcosm.links.getBacklinkDids: get: operationId: getBacklinkDids tags: [links] summary: List distinct DIDs linking to a target description: > A list of distinct DIDs (identities) with links to a target.
Note: the Constellation docs title this section "getDistinct" but the worked example uses the path `blue.microcosm.links.getBacklinkDids`, which is treated as authoritative here. parameters: - $ref: '#/components/parameters/SubjectDistinct' - $ref: '#/components/parameters/Source' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' responses: '200': description: A page of distinct linking DIDs. content: application/json: schema: $ref: '#/components/schemas/DistinctDidsResponse' '400': $ref: '#/components/responses/BadRequest'
/xrpc/blue.microcosm.links.getManyToMany: get: operationId: getManyToMany tags: [links] summary: List many-to-many join records description: > A list of many-to-many join records linking to a target and a secondary target. parameters: - $ref: '#/components/parameters/Subject' - $ref: '#/components/parameters/Source' - $ref: '#/components/parameters/PathToOther' - $ref: '#/components/parameters/DidFilter' - $ref: '#/components/parameters/OtherSubject' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' responses: '200': description: A page of many-to-many join records. content: application/json: schema: $ref: '#/components/schemas/ManyToManyResponse' '400': $ref: '#/components/responses/BadRequest'
/xrpc/blue.microcosm.links.getManyToManyCounts: get: operationId: getManyToManyCounts tags: [links] summary: Counts over many-to-many join records description: Counts of many-to-many join records by secondary target. parameters: - $ref: '#/components/parameters/Subject' - $ref: '#/components/parameters/Source' - $ref: '#/components/parameters/PathToOther' - $ref: '#/components/parameters/DidFilter' - $ref: '#/components/parameters/OtherSubject' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' responses: '200': description: A page of counts grouped by secondary target. content: application/json: schema: $ref: '#/components/schemas/ManyToManyCountsResponse' '400': $ref: '#/components/responses/BadRequest'
/links: get: operationId: getLinksLegacy tags: [legacy] deprecated: true summary: '[DEPRECATED] List records linking to a target' description: > Deprecated. Use `GET /xrpc/blue.microcosm.links.getBacklinks`. Remains supported for the foreseeable future. parameters: - $ref: '#/components/parameters/Target' - $ref: '#/components/parameters/Collection' - $ref: '#/components/parameters/Path' - $ref: '#/components/parameters/DidFilter' - name: from_dids in: query deprecated: true description: 'Deprecated. Use `did` instead. Comma-separated list of DIDs.' schema: type: string example: did:plc:vc7f4oafdgxsihk4cry2xpze,did:plc:vc7f4oafdgxsihk4cry2xpze - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Reverse' - $ref: '#/components/parameters/Cursor' responses: '200': description: A page of backlink records. content: application/json: schema: $ref: '#/components/schemas/BacklinksResponse' '400': $ref: '#/components/responses/BadRequest'
/links/distinct-dids: get: operationId: getDistinctDidsLegacy tags: [legacy] summary: List distinct DIDs linking to a target description: A list of distinct DIDs (identities) with links to a target. parameters: - $ref: '#/components/parameters/Target' - $ref: '#/components/parameters/Collection' - $ref: '#/components/parameters/Path' - $ref: '#/components/parameters/Cursor' responses: '200': description: A page of distinct linking DIDs. content: application/json: schema: $ref: '#/components/schemas/DistinctDidsResponse' '400': $ref: '#/components/responses/BadRequest'
/links/count: get: operationId: getLinksCountLegacy tags: [legacy] deprecated: true summary: '[DEPRECATED] Count of links pointing at a target' description: > Deprecated. Use `GET /xrpc/blue.microcosm.links.getBacklinksCount`. The total number of links pointing at a given target. parameters: - $ref: '#/components/parameters/Target' - $ref: '#/components/parameters/Collection' - $ref: '#/components/parameters/Path' - $ref: '#/components/parameters/Cursor' responses: '200': description: The total link count. content: application/json: schema: $ref: '#/components/schemas/CountResponse' '400': $ref: '#/components/responses/BadRequest'
/links/count/distinct-dids: get: operationId: getDistinctDidsCountLegacy tags: [legacy] summary: Count of distinct DIDs linking to a target description: The total number of DIDs (identities) with links to a given target. parameters: - $ref: '#/components/parameters/Target' - $ref: '#/components/parameters/Collection' - $ref: '#/components/parameters/Path' - $ref: '#/components/parameters/Cursor' responses: '200': description: The distinct-DID count. content: application/json: schema: $ref: '#/components/schemas/CountResponse' '400': $ref: '#/components/responses/BadRequest'
/links/all: get: operationId: getAllLinks tags: [legacy] summary: All sources with links to a target description: > Show all sources with links to a target, including linking record counts and distinct linking DIDs. parameters: - $ref: '#/components/parameters/Target' responses: '200': description: All link sources for the target, with counts. content: application/json: schema: $ref: '#/components/schemas/AllLinksResponse' '400': $ref: '#/components/responses/BadRequest'
/links/all/count: get: operationId: getAllLinksCount tags: [legacy] deprecated: true summary: '[DEPRECATED] Total counts of all links by collection and path' description: > Deprecated. Use `GET /links/all` instead. The total counts of all links pointing at a given target, by collection and path. parameters: - $ref: '#/components/parameters/Target' responses: '200': description: All link counts for the target, by collection and path. content: application/json: schema: $ref: '#/components/schemas/AllLinksResponse' '400': $ref: '#/components/responses/BadRequest'
components: parameters: Subject: name: subject in: query required: true description: > The target being linked to (URL-encoded). A DID, an AT-URI, or a URI. schema: $ref: '#/components/schemas/Target' example: at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r SubjectDistinct: name: subject in: query required: true description: > The target being linked to (URL-encoded). A DID or an AT-URI. schema: $ref: '#/components/schemas/Target' example: at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r Source: name: source in: query required: true description: > A link source — a collection NSID and a JSON path, joined by `:`, e.g. `app.bsky.feed.like:subject.uri`. schema: type: string example: app.bsky.feed.like:subject.uri PathToOther: name: pathToOther in: query required: true description: Path to the secondary link in the many-to-many record. schema: type: string example: subject DidFilter: name: did in: query required: false description: > Filter links to those from specific identities. Repeat the parameter to filter by multiple DIDs. schema: type: array items: type: string style: form explode: true example: [did:plc:vc7f4oafdgxsihk4cry2xpze] OtherSubject: name: otherSubject in: query required: false description: > Filter secondary links to specific subjects. Repeat the parameter to filter by multiple subjects. schema: type: array items: $ref: '#/components/schemas/Target' style: form explode: true Target: name: target in: query required: true description: The target being linked to (URL-encoded). A DID, AT-URI, or URI. schema: $ref: '#/components/schemas/Target' example: at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r Collection: name: collection in: query required: true description: A record NSID. schema: type: string example: app.bsky.feed.like Path: name: path in: query required: true description: > URL-encoded JSON-path-ish location of the link within the record. The special path `.` represents the record's rkey. schema: type: string example: .subject.uri Limit: name: limit in: query required: false description: Number of results to return. schema: type: integer minimum: 1 maximum: 100 default: 16 Reverse: name: reverse in: query required: false description: Return links in reverse order. schema: type: boolean default: false Cursor: name: cursor in: query required: false description: > Pagination cursor. Paged responses include a `cursor` property; when it is `null`, no more data is available. Otherwise, repeat the request with this value to fetch the next page. schema: type: string
responses: BadRequest: description: Invalid or missing parameters. content: application/json: schema: $ref: '#/components/schemas/Error'
schemas: Target: type: string description: > A DID (e.g. `did:plc:hdhoaan3xa3jiuq4fg4mefid`), an AT-URI (e.g. `at://did:plc:.../app.bsky.feed.post/3lgu4lg6j2k2v`), or a URI (e.g. `https://example.com`). examples: - did:plc:hdhoaan3xa3jiuq4fg4mefid - at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3lgu4lg6j2k2v - https://example.com Cursor: type: [string, 'null'] description: > Pagination cursor. `null` when no more data is available; otherwise pass back as the `cursor` query parameter to fetch the next page. RecordRef: type: object description: A reference to a single indexed linking record on a PDS. required: [did, collection, rkey] properties: did: type: string description: The DID of the identity whose record contains the link. collection: type: string description: The collection NSID of the linking record. rkey: type: string description: The record key of the linking record. BacklinksResponse: type: object required: [total, records] properties: total: type: integer description: The total number of links pointing at the subject. records: type: array items: $ref: '#/components/schemas/RecordRef' cursor: $ref: '#/components/schemas/Cursor' DistinctDidsResponse: type: object required: [total, linking_dids] properties: total: type: integer description: The total number of distinct linking identities. linking_dids: type: array items: type: string description: Distinct DIDs (identities) linking to the subject. cursor: $ref: '#/components/schemas/Cursor' CountResponse: type: object required: [total] properties: total: type: integer description: The total count. cursor: $ref: '#/components/schemas/Cursor' ManyToManyItem: type: object description: A many-to-many join record and the secondary target it points at. required: [linkRecord, otherSubject] properties: linkRecord: $ref: '#/components/schemas/RecordRef' otherSubject: $ref: '#/components/schemas/Target' ManyToManyResponse: type: object required: [items] properties: items: type: array items: $ref: '#/components/schemas/ManyToManyItem' cursor: $ref: '#/components/schemas/Cursor' ManyToManyCount: type: object description: Counts of join records grouped by a secondary subject. required: [subject, total, distinct] properties: subject: $ref: '#/components/schemas/Target' total: type: integer description: Total number of join records pointing at this secondary subject. distinct: type: integer description: Number of distinct identities among those join records. ManyToManyCountsResponse: type: object required: [counts_by_other_subject] properties: counts_by_other_subject: type: array items: $ref: '#/components/schemas/ManyToManyCount' cursor: $ref: '#/components/schemas/Cursor' AllLinksSourceCounts: type: object description: Record and distinct-DID counts for a single (collection, path) link source. required: [records, distinct_dids] properties: records: type: integer description: Number of linking records from this source. distinct_dids: type: integer description: Number of distinct identities linking from this source. AllLinksResponse: type: object description: > All link sources pointing at a target. `links` is a nested map keyed first by collection NSID, then by JSON path, with record and distinct-DID counts at the leaves. required: [links] properties: links: type: object description: Map of collection NSID -> path -> counts. additionalProperties: type: object description: Map of JSON path -> counts. additionalProperties: $ref: '#/components/schemas/AllLinksSourceCounts' Error: type: object properties: error: type: string message: type: string additionalProperties: true