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 is an 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 an Accept header, one of raw, car, tar, dag-json, dag-cbor, json, cbor, ipns-record (see format values and their Accept equivalents (opens new window)); when both are present, format takes precedence over Accept

# GET /ipns/{name}[/{path}][?{params}]

Same as above, but name is a mutable identifier that the gateway resolves to a CID before fetching the content path: either an IPNS name (opens new window) or a domain with a DNSLink record.

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 verifiable response types: application/vnd.ipld.raw (opens new window) (raw blocks), application/vnd.ipld.car (opens new window) (CARs), and application/vnd.ipfs.ipns-record (opens new window) (signed IPNS records).

Raw block requests must ask for CIDs directly (/ipfs/{cid}). CAR requests may include a path (/ipfs/{cid}/{path}), because the CAR response includes the blocks needed to verify path resolution.

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

To request application/vnd.ipld.car (opens new window) response type:

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

TIP

A Client SHOULD include the format query parameter (opens new window) in the request URL, ideally in addition to the Accept header (opens new window). This provides the best interoperability and ensures consistent HTTP cache behavior across various gateway implementations.

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

CAR requests can also fetch only a part of a DAG: dag-scope=block|entity|all (opens new window) controls how much of the DAG around the resolved path is returned, and entity-bytes=from:to (opens new window) requests only the blocks needed for a specific byte range of a file.

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" -L | ipfs-car unpack -o bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q
$ ls ./bafybeiakou6e7hnx4ms2yangplzl6viapsoyo6phlee6bwrg4j2xt37m3q/
1007 - Sustainable - alt.txt
1007 - Sustainable - transcript.txt
1007 - Sustainable.png

# Example: fetching a single raw block from a public gateway

To request application/vnd.ipld.raw (opens new window) response type:

$ curl -H "Accept: application/vnd.ipld.raw" "https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi?format=raw" -L > raw-block.bin
$ ipfs block put --cid-codec=dag-pb raw-block.bin
bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

TIP

A Client SHOULD include the format query parameter (opens new window) in the request URL, ideally in addition to the Accept header (opens new window). This provides the best interoperability and ensures consistent HTTP cache behavior across various gateway implementations.

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

# Specifications

The HTTP Gateway specification for IPFS implementers is available at specs.ipfs.tech (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 testing with gateway-conformance (opens new window) test suite.

Help us improve this site!

Edit this page or open an issue