Indexes

Get the index publication this gateway offers

Returns the signed document listing the bands this gateway's index-swarm sidecar publishes: each index, its bands, and every file in each band with its size and SHA-256. The document carries a detached Ed25519 signature by the gateway's registered observer key, so it verifies against the gateway registry however it was obtained. When HTTPSIG_ENABLED is set, the live response is also signed with HTTPSIG, covering Content-Digest; a client must not require that signature, since the detached one is what proves the document.

The byte routes below serve only what this document lists. 404 when the gateway publishes nothing. Not rate limited, so a client that has run out of tokens can still learn what it could fetch. HEAD is supported.

Every error response on the six /ar-io/indexes routes (document, file by name, blob, torrent, WebSeed and feed) carries Cache-Control: no-store. Only 200, 206 and 304 carry a cacheable value. See docs/index-swarm.md, "Running behind nginx".

Response Body

Get a published index file by name

Serves one file of a published band. Rate limited and priced as data egress. Supports a single byte range; several ranges get the whole file. The bytes are read from the publisher's hard link for the listed digest. 503 with Retry-After while that link is missing or disagrees with the publication during a band update. Success responses carry Cache-Control: public, no-cache, or private, no-cache when the gateway meters these routes (a rate limiter or x402 is configured). Error responses carry Cache-Control: no-store. Only a publisher serves this route; a subscriber answers 404.

Path Parameters

Header Parameters

Response Body

Get a published index file by content address

The same bytes as the named route, addressed by SHA-256, so a client that knows a digest can fetch it from any gateway publishing it. Rate limited, priced and signed like the named route, with the same headers, except that success responses carry Cache-Control: public, max-age=31536000, immutable, or private, max-age=31536000, immutable when the gateway meters the byte routes. Error responses carry Cache-Control: no-store.

Path Parameters

Response Body

Get a published index file as a BitTorrent WebSeed

BEP 19 WebSeed for bands offered as torrents: clients fetch <url><torrent name>/<file>, where the torrent name is derived from the band's file names, sizes and digests (see docs/index-publication.md). Metered, range-capable and cached like the blob route: public or, when the gateway meters the byte routes, private, max-age=31536000, immutable; errors carry Cache-Control: no-store.

Path Parameters

Header Parameters

Response Body

Get a published band's torrent, by its v1 infohash

The .torrent for a band the publication offers as a torrent, at the torrentUrl the band's signed entry names, addressed by the v1 infohash. Not metered. When the gateway knows its public origin (INDEXES_PUBLIC_URL, default https://<ARNS_ROOT_HOST>) and INDEXES_TORRENT_WEBSEED is on (the default), the torrent names its WebSeed, <origin>/ar-io/indexes/webseed/ (BEP 19 url-list), so a stock client can finish a band no peer delivers. That and the trackers are outside the info dictionary, so the infohashes are the publisher's. A client must check the info dictionary against the infohashes in the signed publication before using it: nothing outside it is covered by that signature. When HTTPSIG_ENABLED is set, the response is signed, covering x-ar-io-index-torrent and Content-Digest. Cache-Control: public, max-age=86400; errors carry no-store. HEAD is supported.

Path Parameters

Response Body

Get an RSS feed of an index's torrents

RSS 2.0, one item per band of the index that the publication offers as a torrent, newest heights first. Each item's enclosure is the band's .torrent and its link the magnet, so a BitTorrent client subscribed with an auto-download rule takes every band, and each new one as it is published. guid is urn:btih:<v1 infohash>. Elements in the urn:ar-io:index-feed:1 namespace carry the publisher, sequence, the publication's SHA-256, and each band's id, v2 infohash, heights, torrent name (the folder a client saves it in) and the bands it supersedes. Each enclosure's length is that of the .torrent as served, WebSeed included.

A view of the signed publication and nothing else. Absolute URLs start with INDEXES_PUBLIC_URL (default https://<ARNS_ROOT_HOST>), never with the request's Host header. Not metered. When HTTPSIG_ENABLED is set, the response is signed, covering x-ar-io-index-feed and Content-Digest. HEAD is supported. See docs/index-publication.md, "Following an index in a BitTorrent client".

Path Parameters

Response Body

Announce to the publisher's closed BitTorrent tracker

A BitTorrent tracker announce (BEP 3, compact BEP 23), forwarded by the gateway's Envoy to the index-swarm sidecar's tracker; core never sees it. Answers only for the bands the publication offers as torrents, under either infohash, and fails any other with unregistered torrent. The peer's address is read from X-Forwarded-For, so proxies in front of the gateway must append it. Bodies are bencoded; every response is Cache-Control: no-store. Peers are always listed compactly (peers, and peers6 for IPv6), whatever compact asks. Routed only on the gateway's own host, not on ArNS subdomains, and only by the Envoy image from release 85 on (an older Envoy passes the path to core, which answers 404). See docs/index-swarm.md, "The tracker".

Query Parameters

Response Body