IPFS Docs

# 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.

# 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).

TIP

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

Help us improve this site!