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. :::
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 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 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.
:::
Status codes used at the RPC layer are simple:
200
- The request was processed or is being processed (streaming)500
- RPC endpoint returned an error400
- Malformed RPC, argument type error, etc403
- RPC call forbidden404
- RPC endpoint doesn't exist405
- 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 405
error 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).
add
Add a file or directory to ipfs.
Authorizations:
path 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.
Responses
Request samples
- curl
curl -X POST -F file=@myfile "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
- 200
{- "Bytes": 0,
- "Hash": "string",
- "Name": "string",
- "Size": "string"
}
block_put
Store input as an IPFS block.
Authorizations:
path 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'.
Responses
Request samples
- curl
curl -X POST -F file=@myfile "https://ipfs.infura.io:5001/api/v0/block/put?format=<value>&mhtype=sha2-256&mhlen=-1&pin=false"
Response samples
- 200
{- "Key": "string",
- "Size": 0
}
block_stat
Print information of a raw IPFS block.
Authorizations:
path Parameters
arg required | string The base58 multihash of an existing block to stat. Required: yes. |
Responses
Request samples
- curl
curl -X POST "https://ipfs.infura.io:5001/api/v0/block/stat?arg=<key>"
Response samples
- 200
{- "Key": "string",
- "Size": 0
}
dag_put
Add a dag node to ipfs.
Authorizations:
path 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'.
Responses
Request samples
- curl
curl -X POST -F file=@myfile "https://ipfs.infura.io:5001/api/v0/dag/put?format=cbor&input-enc=json&pin=<value>&hash=<value>"
Response samples
- 200
{- "Cid": {
- "/": "string"
}
}
get
Download IPFS objects.
Authorizations:
path 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
curl -X POST "https://ipfs.infura.io:5001/api/v0/get?arg=<ipfs-path>&output=<value>&archive=<value>&compress=<value>&compression-level=<value>"
object_get
Get and serialize the DAG node named by
Authorizations:
path 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
curl -X POST "https://ipfs.infura.io:5001/api/v0/object/get?arg=<key>&data-encoding=text"
Response samples
- 200
{- "Data": "string",
- "Links": [
- {
- "Hash": "string",
- "Name": "string",
- "Size": 0
}
]
}
object_put
Store input as a DAG object, print its key.
Authorizations:
path 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'.
Responses
Request samples
- curl
curl -X POST -F file=@myfile "https://ipfs.infura.io:5001/api/v0/object/put?inputenc=json&datafieldenc=text&pin=<value>&quiet=<value>"
Response samples
- 200
{- "Hash": "string",
- "Links": [
- {
- "Hash": "string",
- "Name": "string",
- "Size": 0
}
]
}
object_stat
Get stats for the DAG node named by
Authorizations:
path 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
curl -X POST "https://ipfs.infura.io:5001/api/v0/object/stat?arg=<key>&human=<value>"
Response samples
- 200
{- "BlockSize": 0,
- "CumulativeSize": 0,
- "DataSize": 0,
- "Hash": "string",
- "LinksSize": 0,
- "NumLinks": 0
}
pin_add
Pin objects to local storage.
Authorizations:
path Parameters
arg required | string Path to object(s) to be pinned. Required: yes. |
progress | boolean Show progress. Required: no. |
Responses
Request samples
- curl
curl -X POST "https://ipfs.infura.io:5001/api/v0/pin/add?arg=<ipfs-path>&progress=<value>"
Response samples
- 200
{- "Pins": [
- "string"
], - "Progress": 0
}
pin_ls
List objects pinned to local storage.
Authorizations:
path 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
curl -X POST "https://ipfs.infura.io:5001/api/v0/pin/ls?arg=<ipfs-path>&type=all&quiet=<value>&stream=<value>"
Response samples
- 200
{- "PinLsList": {
- "Keys": {
- "<string>": {
- "Type": "string"
}
}
}, - "PinLsObject": {
- "Cid": "string",
- "Type": "string"
}
}
pin_rm
Remove pinned objects from local storage.
Authorizations:
path Parameters
arg required | string Path to object(s) to be unpinned. Required: yes. |
Responses
Request samples
- curl
curl -X POST "https://ipfs.infura.io:5001/api/v0/pin/rm?arg=<ipfs-path>"
Response samples
- 200
{- "Pins": [
- "string"
]
}
pin_update
Update a recursive pin
Authorizations:
path 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
curl -X POST "https://ipfs.infura.io:5001/api/v0/pin/update?arg=<from-path>&arg=<to-path>&unpin=true"
Response samples
- 200
{- "Pins": [
- "string"
]
}
version
Show ipfs version information.
Authorizations:
path 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
curl -X POST "https://ipfs.infura.io:5001/api/v0/version?number=<value>&commit=<value>&repo=<value>&all=<value>"
Response samples
- 200
{- "Commit": "string",
- "Golang": "string",
- "Repo": "string",
- "System": "string",
- "Version": "string"
}