# HTTP Gateway reference
Gateways provide implementation and runtime agnostic HTTP interface for retrieving content-addressed data from IPFS with regular HTTP clients and libraries.
cidis a CID, the root identifier of the requested content path
path– optional path under the root CID
Optional query parameters:
filenamesets the name returned in
truewill skip rendering and force browsers to present a 'Save as' dialog
formatURL-friendly alternative to sending
Before you continue
# 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
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 (
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
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
An alternative is to pass
?format=car URL parameter:
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
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
An alternative is to pass
?format=raw URL parameter:
The HTTP Gateway specification for IPFS implementers is available in ipfs/specs repository (opens new window). Below are links for the most useful specifications.
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)
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).
If you are a gateway operator or an implementer, consider joining Gateway Operators Forum (opens new window)