HTTP Gateway reference

Gateways provide implementation and runtime agnostic HTTP interface for retrieving content-addressed data from IPFS with regular HTTP clients and libraries.

API

GET /ipfs/{cid}[/{path}][?{params}]

• cid is a CID, the root identifier of the requested content path
• path – optional path under the root CID

Optional query parameters:

• filename sets the name returned in Content-Disposition HTTP header
• download set to true will skip rendering and force browsers to present a 'Save as' dialog
• format URL-friendly alternative to sending Accept header

Before you continue

Make sure you understand how to address IPFS on the web and the differences between Path Gateways and Subdomain Gateways.

Trusted vs trustless

Gateways can be used in a trusted or trustless way. HTTP clients are in control; they decide how much trust and work is delegated to the gateway.

Delegating trust

By default, a gateway will take care of UnixFS deserialization and return reassembled files to the client, as if they were stored in a traditional HTTP server. This means all validation happens on the gateway, and clients trust that the gateway is correctly validating content-addressed data before returning it to them.

Example: fetching an UnixFS file from a local gateway

$ curl "http://127.0.0.1:8080/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi" > cat.jpg

TIP

When fetching a CID directly, one can include a filename parameter with file name to be used in Content-Disposition HTTP header: https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi?filename=cat.jpg (opens new window)

Trustless, verifiable retrieval

Clients capable of verifying content-addressed data on their own, should use application/vnd.ipld.raw (opens new window) and application/vnd.ipld.car (opens new window) response types (raw blocks and CARs) and always ask for CIDs directly (/ipfs/{cid}).

This mode of operation removes the need for trusting gateway returns correct data. Client can always verify that returned bytes match the requested CID.

Example: fetching an entire DAG as a CAR stream from a public gateway

Using Accept HTTP header with application/vnd.ipld.car (opens new window) type:

$ curl -H "Accept: application/vnd.ipld.car" "https://ipfs.io/ipfs/bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q" > dag.car
$ ipfs dag import dag.car

TIP

An alternative is to pass ?format=car URL parameter:

https://ipfs.io/ipfs/bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q?format=car (opens new window)

Verify CAR without running full IPFS node

CAR verification does not require running IPFS node. Clients can leverage standalone tools and libraries such as ipfs-car (opens new window):

$ npm i -g ipfs-car
$ curl "https://ipfs.io/ipfs/bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q?format=car" | ipfs-car
$ ls ./bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q/
1007 - Sustainable - alt.txt
1007 - Sustainable - transcript.txt
1007 - Sustainable.png

Example: fetching a single raw block from a public gateway

Using Accept HTTP header with application/vnd.ipld.raw (opens new window) type:

$ curl -H "Accept: application/vnd.ipld.raw" "https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi" > raw-block.bin
$ ipfs block put raw-block.bin
bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

TIP

An alternative is to pass ?format=raw URL parameter:

https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi?format=raw (opens new window)

Specifications

The HTTP Gateway specification for IPFS implementers is available in ipfs/specs repository (opens new window). Below are links for the most useful specifications.

HTTP

These are "low level" gateways that expose IPFS resources over HTTP protocol.

• Path Gateway (opens new window) ← START HERE, other types of gateway are specified as a delta against this specification.
• Trustless Gateway (opens new window) is a subset that returns verifiable response types (raw blocks and CARs)

Web

Special types of gateway which leverage Host header in addition to URL pathname. Designed for website hosting and improved interoperability with web browsers and origin-based security model (opens new window).

• Subdomain Gateway (opens new window)
• DNSLink Website Hosting (opens new window)

TIP

If you are a gateway operator or an implementer, consider joining Gateway Operators Forum (opens new window)