Infura IPFS Documentation (1.0.0)

Infura Support: support@infura.io

Getting started

Generated on 2020-09-22, from go-ipfs v0.7.0.

When an IPFS node is running as a daemon, it exposes an HTTP API that allows you to control the node and run the same commands you can from the command line.

In many cases, using this API this is preferable to embedding IPFS directly in your program — it allows you to maintain peer connections that are longer lived than your app and you can keep a single IPFS node running instead of several if your app can be launched multiple times. In fact, the ipfs CLI commands use this API when operating in online mode.

::: tip This document was autogenerated from go-ipfs. For issues and support, check out the ipfs-http-api-docs repository on GitHub. :::

Alignment with CLI commands

The HTTP API under /api/v0/ is an RPC-style API over HTTP, not a REST API.

Every command usable from the CLI is also available through the HTTP API. For example:

> ipfs swarm peers
/ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ
/ip4/104.236.151.122/tcp/4001/p2p/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx
/ip4/104.236.176.52/tcp/4001/p2p/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z

> curl -X POST https://ipfs.infura.io:5001/api/v0/swarm/peers
{
  "Strings": [
    "/ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ",
    "/ip4/104.236.151.122/tcp/4001/p2p/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx",
    "/ip4/104.236.176.52/tcp/4001/p2p/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z",
  ]
}

Arguments

Arguments are added through the special query string key "arg":

> curl -X POST "https://ipfs.infura.io:5001/api/v0/swarm/disconnect?arg=/ip4/54.93.113.247/tcp/48131/p2p/QmUDS3nsBD1X4XK5Jo836fed7SErTyTuQzRqWaiQAyBYMP"
{
  "Strings": [
    "disconnect QmUDS3nsBD1X4XK5Jo836fed7SErTyTuQzRqWaiQAyBYMP success",
  ]
}

Note that it can be used multiple times to signify multiple arguments.

Flags

Flags are added through the query string. For example, the --encoding=json flag is the &encoding=json query parameter below:

> curl -X POST "https://ipfs.infura.io:5001/api/v0/object/get?arg=QmaaqrHyAQm7gALkRW8DcfGX3u8q9rWKnxEMmf7m9z515w&encoding=json"
{
  "Links": [
    {
      "Name": "index.html",
      "Hash": "QmYftndCvcEiuSZRX7njywX2AGSeHY2ASa7VryCq1mKwEw",
      "Size": 1700
    },
    {
      "Name": "static",
      "Hash": "QmdtWFiasJeh2ymW3TD2cLHYxn1ryTuWoNpwieFyJriGTS",
      "Size": 2428803
    }
  ],
  "Data": "CAE="
}

::: tip Some arguments may belong only to the CLI but appear here too. These usually belong to client-side processing of input, particularly in the add command. :::

HTTP status codes

Status codes used at the RPC layer are simple:

  • 200 - The request was processed or is being processed (streaming)
  • 500 - RPC endpoint returned an error
  • 400 - Malformed RPC, argument type error, etc
  • 403 - RPC call forbidden
  • 404 - RPC endpoint doesn't exist
  • 405 - HTTP Method Not Allowed

Status code 500 means that the function does exist, but IPFS was not able to fulfil the request because of an error. To know that reason, you have to look at the the error message that is usually returned with the body of the response (if no error, check the daemon logs).

Streaming endpoints fail as above, unless they have started streaming. That means they will have sent a 200 status code already. If an error happens during the stream, it will be included in a Trailer response header (some endpoints may additionally include an error in the last streamed object).

A 405error may mean that you are using the wrong HTTP method (i.e. GET instead of POST), or that you are not allowed to call that method (i.e. due to CORS restrictions when making a request from a browser).

Authentication

basicAuth

Security Scheme Type HTTP
HTTP Authorization Scheme basic

add

add

Add a file or directory to IPFS.

Authorizations:
query Parameters
quiet
boolean

Write minimal output. Required: no.

quieter
boolean

Write only final hash. Required: no.

silent
boolean

Write no output. Required: no.

progress
boolean

Stream progress data. Required: no.

trickle
boolean

Use trickle-dag format for dag generation. Required: no.

only-hash
boolean

Only chunk and hash - do not write to disk. Required: no.

wrap-with-directory
boolean

Wrap files with a directory object. Required: no.

chunker
string
Default: "size-262144"

Chunking algorithm, size-[bytes], rabin-[min]-[avg]-[max] or buzhash. Default: size-262144. Required: no.

pin
boolean
Default: "true"

Pin this object when adding. Default: true. Required: no.

raw-leaves
boolean

Use raw blocks for leaf nodes. (experimental). Required: no.

nocopy
boolean

Add the file using filestore. Implies raw-leaves. (experimental). Required: no.

fscache
boolean

Check the filestore for pre-existing blocks. (experimental). Required: no.

cid-version
integer <int32>
Default: null

CID version. Defaults to 0 unless an option that depends on CIDv1 is passed. (experimental). Required: no.

hash
string
Default: "sha2-256"

Hash function to use. Implies CIDv1 if not sha2-256. (experimental). Default: sha2-256. Required: no.

inline
boolean

Inline small blocks into CIDs. (experimental). Required: no.

inline-limit
integer <int32>
Default: 32

Maximum block size to inline. (experimental). Default: 32. Required: no.

Request Body schema: multipart/form-data

Argument path is of file type. This endpoint expects one or several files (depending on the command) in the body of the request as 'multipart/form-data'.

The add command not only allows adding files, but also uploading directories and complex hierarchies.

This happens as follows: Every part in the multipart request is a directory or a file to be added to IPFS.

Directory parts have a special content type application/x-directory. These parts do not carry any data. The part headers look as follows:

Content-Disposition: form-data; name="file"; filename="folderName"
Content-Type: application/x-directory

File parts carry the file payload after the following headers:

Abspath: /absolute/path/to/file.txt
Content-Disposition: form-data; name="file"; filename="folderName%2Ffile.txt"
Content-Type: application/octet-stream

...contents...

The above file includes its path in the "folderName/file.txt" hierarchy and IPFS will therefore be able to add it inside "folderName". The parts declaring the directories are optional when they have files inside and will be inferred from the filenames. In any case, a depth-first traversal of the directory tree is recommended to order the different parts making the request.

The Abspath header is included for filestore/urlstore features that are enabled with the nocopy option and it can be set to the location of the file in the filesystem (within the IPFS root), or to its full web URL.

object

Responses

Request samples

curl -X POST -F [email protected] "https://ipfs.infura.io:5001/api/v0/add?quiet=<value>&quieter=<value>&silent=<value>&progress=<value>&trickle=<value>&only-hash=<value>&wrap-with-directory=<value>&chunker=size-262144&pin=true&raw-leaves=<value>&nocopy=<value>&fscache=<value>&cid-version=<value>&hash=sha2-256&inline=<value>&inline-limit=32"

Response samples

Content type
application/json
{
  • "Bytes": 0,
  • "Hash": "string",
  • "Name": "string",
  • "Size": "string"
}

block

block_get

Get a raw IPFS block.

Authorizations:
query Parameters
arg
required
string

The base58 multihash of an existing block to get. Required: yes.

Responses

Request samples

curl -X POST "https://ipfs.infura.io:5001/api/v0/block/get?arg=<key>"

Response samples

Content type
application/json
{ }

block_put

Store input as an IPFS block.

Authorizations:
query Parameters
format
string

cid format for blocks to be created with. Required: no.

mhtype
string
Default: "sha2-256"

multihash hash function. Default: sha2-256. Required: no.

mhlen
integer <int32>
Default: -1

multihash hash length. Default: -1. Required: no.

pin
boolean
Default: "false"

pin added blocks recursively. Default: false. Required: no.

Request Body schema: multipart/form-data

Argument data is of file type. This endpoint expects one or several files (depending on the command) in the body of the request as 'multipart/form-data'.

object

Responses

Request samples

curl -X POST -F [email protected] "https://ipfs.infura.io:5001/api/v0/block/put?format=<value>&mhtype=sha2-256&mhlen=-1&pin=false"

Response samples

Content type
application/json
{
  • "Key": "string",
  • "Size": 0
}

block_stat

Print information of a raw IPFS block.

Authorizations:
query Parameters
arg
required
string

The base58 multihash of an existing block to stat. Required: yes.

Responses

Request samples

curl -X POST "https://ipfs.infura.io:5001/api/v0/block/stat?arg=<key>"

Response samples

Content type
application/json
{
  • "Key": "string",
  • "Size": 0
}

cat

cat

Show IPFS object data.

Authorizations:
query Parameters
arg
required
string

The path to the IPFS object(s) to be outputted. Required: yes.

offset
integer <int64>

Byte offset to begin reading from. Required: no.

length
integer <int64>

Maximum number of bytes to read. Required: no.

Responses

Request samples

curl -X POST "https://ipfs.infura.io:5001/api/v0/cat?arg=<ipfs-path>&offset=<value>&length=<value>"

Response samples

Content type
application/json
{ }

dag

dag_get

Get a dag node from IPFS.

Authorizations:
query Parameters
arg
required
string

The object to get Required: yes.

Responses

Request samples

curl -X POST "https://ipfs.infura.io:5001/api/v0/dag/get?arg=<ref>"

Response samples

Content type
application/json
{ }

dag_put

Add a dag node to IPFS.

Authorizations:
query Parameters
format
string
Default: "cbor"

Format that the object will be added as. Default: cbor. Required: no.

input-enc
string
Default: "json"

Format that the input object will be. Default: json. Required: no.

pin
boolean

Pin this object when adding. Required: no.

hash
string
Default: ""

Hash function to use. Default: . Required: no.

Request Body schema: multipart/form-data

Argument object data is of file type. This endpoint expects one or several files (depending on the command) in the body of the request as 'multipart/form-data'.

object

Responses

Request samples

curl -X POST -F [email protected] "https://ipfs.infura.io:5001/api/v0/dag/put?format=cbor&input-enc=json&pin=<value>&hash=<value>"

Response samples

Content type
application/json
{
  • "Cid": {
    }
}

dag_resolve

Resolve IPLD block.

Authorizations:
query Parameters
arg
required
string

The path to resolve Required: yes.

Responses

Request samples

curl -X POST "https://ipfs.infura.io:5001/api/v0/dag/resolve?arg=<ref>"

Response samples

Content type
application/json
{
  • "Cid": {
    },
  • "RemPath": "string"
}

get

get

Download IPFS objects.

Authorizations:
query Parameters
arg
required
string

The path to the IPFS object(s) to be outputted. Required: yes.

output
string

The path where the output should be stored. Required: no.

archive
boolean

Output a TAR archive. Required: no.

compress
boolean

Compress the output with GZIP compression. Required: no.

compression-level
integer <int32>

The level of compression (1-9). Required: no.

Responses

Request samples

curl -X POST "https://ipfs.infura.io:5001/api/v0/get?arg=<ipfs-path>&output=<value>&archive=<value>&compress=<value>&compression-level=<value>"

Response samples

Content type
application/json
{ }

object

object_data

Output the raw bytes of an IPFS object.

Authorizations:
query Parameters
arg
required
string

Key of the object to retrieve, in base58-encoded multihash format. Required: yes.

Responses

Request samples

curl -X POST "https://ipfs.infura.io:5001/api/v0/object/data?arg=<key>"

Response samples

Content type
application/json
{ }

object_get

Get and serialize the DAG node named by .

Authorizations:
query Parameters
arg
required
string

Key of the object to retrieve, in base58-encoded multihash format. Required: yes.

data-encoding
string
Default: "text"

Encoding type of the data field, either "text" or "base64". Default: text. Required: no.

Responses

Request samples

curl -X POST "https://ipfs.infura.io:5001/api/v0/object/get?arg=<key>&data-encoding=text"

Response samples

Content type
application/json
{
  • "Data": "string",
  • "Links": [
    ]
}

object_put

Store input as a DAG object, print its key.

Authorizations:
query Parameters
inputenc
string
Default: "json"

Encoding type of input data. One of: {"protobuf", "json"}. Default: json. Required: no.

datafieldenc
string
Default: "text"

Encoding type of the data field, either "text" or "base64". Default: text. Required: no.

pin
boolean

Pin this object when adding. Required: no.

quiet
boolean

Write minimal output. Required: no.

Request Body schema: multipart/form-data

Argument data is of file type. This endpoint expects one or several files (depending on the command) in the body of the request as 'multipart/form-data'.

object

Responses

Request samples

curl -X POST -F [email protected] "https://ipfs.infura.io:5001/api/v0/object/put?inputenc=json&datafieldenc=text&pin=<value>&quiet=<value>"

Response samples

Content type
application/json
{
  • "Hash": "string",
  • "Links": [
    ]
}

object_stat

Get stats for the DAG node named by .

Authorizations:
query Parameters
arg
required
string

Key of the object to retrieve, in base58-encoded multihash format. Required: yes.

human
boolean

Print sizes in human readable format (e.g., 1K 234M 2G). Required: no.

Responses

Request samples

curl -X POST "https://ipfs.infura.io:5001/api/v0/object/stat?arg=<key>&human=<value>"

Response samples

Content type
application/json
{
  • "BlockSize": 0,
  • "CumulativeSize": 0,
  • "DataSize": 0,
  • "Hash": "string",
  • "LinksSize": 0,
  • "NumLinks": 0
}

pin

pin_add

Pin objects to local storage.

Authorizations:
query Parameters
arg
required
string

Path to object(s) to be pinned. Required: yes.

progress
boolean

Show progress. Required: no.

Responses

Request samples

curl -X POST "https://ipfs.infura.io:5001/api/v0/pin/add?arg=<ipfs-path>&progress=<value>"

Response samples

Content type
application/json
{
  • "Pins": [
    ],
  • "Progress": 0
}

pin_ls

List objects pinned to local storage.

Authorizations:
query Parameters
arg
string

Path to object(s) to be listed. Required: no.

type
string
Default: "all"

The type of pinned keys to list. Can be "direct", "indirect", "recursive", or "all". Default: all. Required: no.

quiet
boolean

Write just hashes of objects. Required: no.

stream
boolean

Enable streaming of pins as they are discovered. Required: no.

Responses

Request samples

curl -X POST "https://ipfs.infura.io:5001/api/v0/pin/ls?arg=<ipfs-path>&type=all&quiet=<value>&stream=<value>"

Response samples

Content type
application/json
{
  • "PinLsList": {
    },
  • "PinLsObject": {
    }
}

pin_rm

Remove pinned objects from local storage.

Authorizations:
query Parameters
arg
required
string

Path to object(s) to be unpinned. Required: yes.

Responses

Request samples

curl -X POST "https://ipfs.infura.io:5001/api/v0/pin/rm?arg=<ipfs-path>"

Response samples

Content type
application/json
{
  • "Pins": [
    ]
}

pin_update

Update a recursive pin.

Authorizations:
query Parameters
arg
required
string

Path to old object. Required: yes.

arg
required
string

Path to a new object to be pinned. Required: yes.

unpin
boolean
Default: "true"

Remove the old pin. Default: true. Required: no.

Responses

Request samples

curl -X POST "https://ipfs.infura.io:5001/api/v0/pin/update?arg=<from-path>&arg=<to-path>&unpin=true"

Response samples

Content type
application/json
{
  • "Pins": [
    ]
}

version

version

Show IPFS version information.

Authorizations:
query Parameters
number
boolean

Only show the version number. Required: no.

commit
boolean

Show the commit hash. Required: no.

repo
boolean

Show repo version. Required: no.

all
boolean

Show all version information. Required: no.

Responses

Request samples

curl -X POST "https://ipfs.infura.io:5001/api/v0/version?number=<value>&commit=<value>&repo=<value>&all=<value>"

Response samples

Content type
application/json
{
  • "Commit": "string",
  • "Golang": "string",
  • "Repo": "string",
  • "System": "string",
  • "Version": "string"
}