Content Retrieval

How to retrieve the content a domain points to over an IPFS gateway.

Overview

Some domains may have content records pointing to decentralized content, like an IPFS CID. Retrieval of this content usually takes place through either a local IPFS node, or a public IPFS gateway. A GET request to the /domain/ipfs/ endpoint with a domain and gateway URL provided gives a method to retrieve a given domain's content in a single request.

Requests for content retrieval over an IPFS gateway are restricted to a list of approved gateway URLs. This includes both public gateways and popular restricted gateways. The approved gateway URLs that may be passed in a request are:

• gateway.sgr-a.xyz

• ipfs.io

• gateway.ipfs.io

• dweb.link

• cloudflare-ipfs.com

• cf-ipfs.com

• infura-ipfs.io

• gateway.pinata.cloud

• ipfs.filebase.io

Any one of these gateway URLs may be passed alongside a valid ENS domain containing either IPFS content, or IPNS content that has generated a cached CID.

Request Spec

  /domain/ipfs/{domain}/{gatewayURL}:
    get:
      summary: Submit an ENS Domain for IPFS content retrieval over a passed Gateway URL.
      parameters:
        - in: path
          name: domain
          required: true
          description: An ENS domain name.
          schema:
            type: string
        - in: path
          name: gatewayURL
          required: true
          description: An approved IPFS Gateway URL.
          schema:
            type: string

Sending the Request

Sending a request to the /domain/ipfs endpoint requires a valid API Key top be provided in the x-api-key header, and that an ENS domain name along with an approved IPFS gateway URL be provided.

Content Retrieval Request

curl -x GET "x-api-key: Your-API-Key" https://api.sgr-a.xyz/domain/ipfs/ethereum.eth/dweb.link

When a Content Retrieval Request for a domain over IPFS completes successfully, the returned output will contain the retrieved content. Unlike other requests, there is not a set format to expect in the response, as the response directly contains the domain's resolved content. For example, if the domain example.eth points to an IPFS CID of an HTML site, the request response will contain index.html. If the request fails, the response will contain a JSON object with an error message indicating the reason of the failure.