Routing V1 HTTP API

status: reliable
Gus Eggert GitHub
Masih H. Derkani GitHub
Henrique Dias GitHub
Commit History
GitHub ipfs/specs (pull requests, new issue, open issues)

Delegated routing is a mechanism for IPFS implementations to use for offloading content routing and naming to another process/server. This specification describes a vendor-agnostic HTTP API for delegated content routing.

1. API Specification

The Routing HTTP API uses the application/json content type by default. For IPNS Names, the verifiable application/vnd.ipfs.ipns-record content type is used.

As such, human-readable encodings of types are preferred. This specification may be updated in the future with a compact application/cbor encoding, in which case compact encodings of the various types would be used.

2. Common Data Types

Until required for business logic, servers should treat these types as opaque strings, and should preserve unknown JSON fields.

2.1 Versioning

This API uses a standard version prefix in the path, such as /v1/.... If a backwards-incompatible change must be made, then the version number should be increased.

2.2 Provider Records

A provider record contains information about a content provider, including the transfer protocol and any protocol-specific information useful for fetching the content from the provider.

The information required to write a record to a router ("write" provider records) may be different than the information contained when reading provider records ("read" provider records).

For example, indexers may require a signature in bitswap write records for authentication of the peer contained in the record, but the read records may not include this authentication information.

Both read and write provider records have a minimal required schema as follows:

    "Protocol": "<transfer_protocol_name>",
    "Schema": "<transfer_protocol_schema>",


Specifications for some transfer protocols are provided in the "Transfer Protocols" section.

3. Content Providers API

3.1 GET /routing/v1/providers/{cid}

3.1.1 Path Parameters

  • cid is the CID to fetch provider records for.

3.1.2 Response Status Codes

  • 200 (OK): the response body contains 0 or more records.
  • 404 (Not Found): must be returned if no matching records are found.
  • 422 (Unprocessable Entity): request does not conform to schema or semantic constraints.

3.1.3 Response Body

  "Providers": [
      "Protocol": "<protocol_name>",
      "Schema": "<schema>",

Response limit: 100 providers

Each object in the Providers list is a read provider record.


4.1 GET /routing/v1/ipns/{name}

4.1.1 Path Parameters

  • name is the IPNS Name to resolve, encoded as CIDv1.

4.1.2 Response Status Codes

  • 200 (OK): the response body contains the IPNS Record for the given IPNS Name.
  • 404 (Not Found): must be returned if no matching records are found.
  • 406 (Not Acceptable): requested content type is missing or not supported. Error message returned in body should inform the user to retry with Accept: application/vnd.ipfs.ipns-record.

4.1.3 Response Headers

  • Etag: a globally unique opaque string used for HTTP caching. MUST be derived from the protobuf record returned in the body.
  • Cache-Control: max-age={TTL}: cache TTL returned with IPNS Record that has[TTL] > 0. When present, SHOULD match the TTL value from the record. When record was not found (HTTP 404) or has no TTL (value is 0), implementation SHOULD default to max-age=60.

4.1.4 Response Body

The response body contains a IPNS Record serialized using the verifiable application/vnd.ipfs.ipns-record protobuf format.

4.2 PUT /routing/v1/ipns/{name}

4.2.1 Path Parameters

  • name is the IPNS Name to publish, encoded as CIDv1.

4.2.2 Request Body

The content body must be a application/vnd.ipfs.ipns-record serialized IPNS Record, with a valid signature matching the name path parameter.

4.2.3 Response Status Codes

  • 200 (OK): the provided IPNS Record was published.
  • 400 (Bad Request): the provided IPNS Record or IPNS Name are not valid.
  • 406 (Not Acceptable): submitted content type is not supported. Error message returned in body should inform the user to retry with Content-Type: application/vnd.ipfs.ipns-record.

5. Pagination

This API does not support pagination, but optional pagination can be added in a backwards-compatible spec update.

6. Streaming

JSON-based endpoints support streaming requests made with Accept: application/x-ndjson HTTP Header.

Steaming responses are formatted as Newline Delimited JSON (ndjson), with one result per line:

{"Schema": "<schema>", ...}
{"Schema": "<schema>", ...}
{"Schema": "<schema>", ...}

Streaming is opt-in and backwards-compatibile with clients and servers that do not support streaming:

7. Error Codes

8. CORS and Web Browsers

Browser interoperability requires implementations to support CORS.

JavaScript client running on a third-party Origin must be able to send HTTP request to the endpoints defined in this specification, and read the received values. This means HTTP server implementing this API must (1) support CORS preflight requests sent as HTTP OPTIONS, and (2) always respond with headers that remove CORS limits, allowing every site to query the API for results:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS

9. Known Transfer Protocols

This section contains a non-exhaustive list of known transfer protocols (by name) that may be supported by clients and servers.

9.1 Bitswap

9.1.1 Bitswap Read Provider Records

  "Protocol": "transport-bitswap",
  "Schema": "bitswap",
  "ID": "12D3K...",
  "Addrs": ["/ip4/..."]
  • ID: the Peer ID to contact
  • Addrs: a list of known multiaddrs for the peer
    • This list may be incomplete or incorrect and should only be treated as hints to improve performance by avoiding extra peer lookups

The server should respect a passed transport query parameter by filtering against the Addrs list.

9.2 Filecoin Graphsync

9.2.1 Filecoin Graphsync Read Provider Records

  "Protocol": "transport-graphsync-filecoinv1",
  "Schema": "graphsync-filecoinv1",
  "ID": "12D3K...",
  "Addrs": ["/ip4/..."],
  "PieceCID": "<cid>",
  "VerifiedDeal": true,
  "FastRetrieval": true
  • ID: the Peer ID of the provider
  • Addrs: a list of known multiaddrs for the provider
  • PieceCID: the CID of the piece within which the data is stored
  • VerifiedDeal: whether the deal corresponding to the data is verified
  • FastRetrieval: whether the provider claims there is an unsealed copy of the data available for fast retrieval

A. References

Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: