FISLFinding Internet Structures & Links

The location record

One record states one set of retrieval locations for the requested CID, and who announced them if the indexer knows.

The addr object

Each entry in addrs describes one location.

Expiry

The record's expires is a ceiling. An addr's effective expiry is the earliest of its own and the record's, whichever are present; an addr without its own inherits the record's; an addr with neither has no stated expiry.

This lets one record mix a stable mirror with a short-lived one without re-publishing on the shortest lifetime's cadence.

Lookup API

GET /routing/locations/{cid}/{format}

{cid} is a DASL or BDASL CID in string form. DASL CIDs have exactly one valid string encoding, so no normalization is needed and the path is maximally cacheable. {format} is json or jsonl.

Response formats

The format is named in the path, never negotiated with Accept. A format added by a later revision takes its own path segment, and an indexer that does not implement it answers 404.

{
  "locations": [
    {
      "publisher": "did:plc:ewvi7nxzyoun6zhxrhs64oiz",
      "addrs": [
        {
          "url": "https://berjon.com/.well-known/rasl/bafkreifn5yxi7nkftsn46b6x26grda57ict7md2xuvfbsgkiahe2e7vnq4"
        },
        { "url": "https://mirror.example.com/kitten.jpg", "expires": "2026-09-01T00:00:00Z" }
      ],
      "size": 94201,
      "expires": "2026-09-18T00:00:00Z"
    }
  ]
}

{"publisher":"did:plc:ewvi7nxzyoun6zhxrhs64oiz","addrs":[{"url":"https://berjon.com/.well-known/rasl/bafkreifn5yxi7nkftsn46b6x26grda57ict7md2xuvfbsgkiahe2e7vnq4"}],"size":94201,"expires":"2026-09-18T00:00:00Z"}
{"publisher":"did:web:mirror.example.com","addrs":[{"url":"https://mirror.example.com/kitten.jpg","expires":"2026-08-30T00:00:00Z"}],"expires":"2026-09-01T00:00:00Z"}
{"addrs":[{"url":"https://cache.example.net/kitten.jpg"}]}

JSONL exists for streaming: an indexer can write each record as it finds it, rather than buffering the full set. Clients must parse lines incrementally and must not assume a bound on how many arrive. The empty answer is an empty body with status 200.

Caching

Responses should carry Cache-Control: public, max-age={ttl}, where ttl does not exceed the time until the earliest expiry in the response. With stale-while-revalidate, the bound covers the total:

max-age + stale-while-revalidate <= time to earliest expiry

Exceed it and a cache answers with records the client then discards as expired: the lookup succeeds and gives the client nothing to try. Within the bound a stale answer is cheap — one failed fetch, then the next addr — so an indexer can keep max-age short and still serve most requests from cache.

CORS

Indexers must be queryable from a browser on any origin:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS

Transport agnosticity

An addr is a URL and nothing more. The scheme names the transport, so the transport is encapsulated by the URL and never appears as a separate field. A new transport needs a scheme and a specification of it — not a new field, a registry, or a new version of this API.

Indexers treat URLs opaquely and must not drop, rewrite, or reject an addr whose scheme they do not know. Selection is the client's job. So one record can mix transports, and each client takes what it can use:

{
  "publisher": "did:plc:ewvi7nxzyoun6zhxrhs64oiz",
  "addrs": [
    {
      "url": "https://berjon.com/.well-known/rasl/bafkreifn5yxi7nkftsn46b6x26grda57ict7md2xuvfbsgkiahe2e7vnq4"
    },
    { "url": "radiroh://25igmk4u75iqsbosfvep5sxoozazizgoxfnuqzsnl22pbddig5ra" }
  ],
  "expires": "2026-09-18T00:00:00Z"
}

A URL need not carry network coordinates. radiroh:// names an iroh endpoint — a public key — and leaves resolution to the client; the CID is absent because the client already holds it. One such URL covers every CID that endpoint serves.