Indexes

Get the index publication this gateway offers

Returns the signed document listing the index artifacts 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 three /ar-io/indexes routes carries Cache-Control: no-store, so a cache in front of the gateway never keeps it. Only 200, 206 and 304 carry a cacheable value.

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, which resuming downloaders use. The name is only a lookup key: the bytes are read from the publisher's hard link for the listed digest, so a band rebuilt in place is never served under the old digest. 503 with Retry-After while that link is missing or disagrees with the publication during a band update. Sent with Cache-Control: public, no-cache, because a name is reused when a band is rebuilt; fetch by digest from the blob route for anything a cache should keep. When the gateway meters these routes (a rate limiter or x402 is configured) success responses carry private, no-cache instead, so a shared cache cannot replay paid bytes to a client that has not paid. Error responses carry Cache-Control: no-store.

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. Immutable by construction. 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, so a shared cache cannot replay paid bytes. Error responses carry Cache-Control: no-store, so a cache never keeps a 402 or 429 for a year under this URL.

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>. The torrent name is the first 16 hex characters of SHA-256 over one line per file, <name>\0<size>\0<sha256 hex>\n, in bytewise name order (see docs/index-publication.md), so the address cannot change meaning. 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. Subscribers turn it on only when peers are not delivering, since it is the publisher's metered tier.

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, so a band rebuilt under the same id gets a new address. Not metered. A client must check it against the infohashes in the signed publication before using it, and should hand an engine only the info dictionary and trackers it trusts: nothing outside the info dictionary is covered by the signature. Cache-Control: public, max-age=86400 (only the tracker list, outside the infohash, can change under one address); errors carry no-store.

Path Parameters

Response Body