# Kubo RPC API v0 reference

Generated on 2023-07-03, from kubo v0.21.0

This document was autogenerated from v0.21.0 (opens new window). For issues and support, check out the http-api-docs (opens new window) generator on GitHub.

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

In many cases, using this RPC API 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 RPC API when operating in online mode.

NEVER EXPOSE THE RPC API TO THE PUBLIC INTERNET

The RPC API provides admin-level access to your Kubo IPFS node, including /api/v0/config.

It is bound to localhost by default on purpose. You should never expose it to the public internet, just like you would never expose a SQL database or other backend service.

If you are looking for an interface designed for browsers and public internet, consider implementation-agnostic HTTP Gateway instead.

# Getting started

# Alignment with CLI commands

The 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 RPC 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 http://127.0.0.1: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 "http://127.0.0.1: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 "http://127.0.0.1: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="
}

Some flags may be repeated. For example, the --status flag may be reused as below:

> curl -X POST "http://127.0.0.1:5001/api/v0/pin/remote/service/ls?name=myservice&status=pinned&status=pinning"

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.

Additionally, as a convenience certain CLI commands may allow passing repeated flags as delimited lists such as ipfs pin remote service ls --status=pinned,pinning; however, this does not apply to the HTTP API.

# 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 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), and a 403 error occurs in a browser due to Origin / CORS.

# Origin-based security

When a request is sent from a browser, HTTP RPC API follows the Origin-based security model (opens new window), and expects the Origin HTTP header to be present. The API will return HTTP Error 403 when Origin is missing, does not match the API port, or is not safelisted via API.HTTPHeaders.Access-Control-Allow-Origin in the config.

# RPC commands

# /api/v0/add

Add a file or directory to IPFS.

# Arguments

quiet [bool]: Write minimal output. Required: no.
quieter [bool]: Write only final hash. Required: no.
silent [bool]: Write no output. Required: no.
progress [bool]: Stream progress data. Required: no.
trickle [bool]: Use trickle-dag format for dag generation. Required: no.
only-hash [bool]: Only chunk and hash - do not write to disk. Required: no.
wrap-with-directory [bool]: Wrap files with a directory object. Required: no.
chunker [string]: Chunking algorithm, size-[bytes], rabin-[min]-[avg]-[max] or buzhash. Default: size-262144. Required: no.
raw-leaves [bool]: Use raw blocks for leaf nodes. Required: no.
nocopy [bool]: Add the file using filestore. Implies raw-leaves. (experimental). Required: no.
fscache [bool]: Check the filestore for pre-existing blocks. (experimental). Required: no.
cid-version [int]: CID version. Defaults to 0 unless an option that depends on CIDv1 is passed. Passing version 1 will cause the raw-leaves option to default to true. Required: no.
hash [string]: Hash function to use. Implies CIDv1 if not sha2-256. (experimental). Default: sha2-256. Required: no.
inline [bool]: Inline small blocks into CIDs. (experimental). Required: no.
inline-limit [int]: Maximum block size to inline. (experimental). Default: 32. Required: no.
pin [bool]: Pin locally to protect added files from garbage collection. Default: true. Required: no.
to-files [string]: Add reference to Files API (MFS) at the provided path. Required: no.

# Request Body

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.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Bytes": "<int64>",
  "Hash": "<string>",
  "Name": "<string>",
  "Size": "<string>"
}

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/add?quiet=<value>&quieter=<value>&silent=<value>&progress=<value>&trickle=<value>&only-hash=<value>&wrap-with-directory=<value>&chunker=size-262144&raw-leaves=<value>&nocopy=<value>&fscache=<value>&cid-version=<value>&hash=sha2-256&inline=<value>&inline-limit=32&pin=true&to-files=<value>"

# /api/v0/bitswap/ledger

Show the current ledger for a peer.

# Arguments

arg [string]: The PeerID (B58) of the ledger to inspect. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Exchanged": "<uint64>",
  "Peer": "<string>",
  "Recv": "<uint64>",
  "Sent": "<uint64>",
  "Value": "<float64>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/bitswap/ledger?arg=<peer>"

# /api/v0/bitswap/reprovide

Trigger reprovider.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/bitswap/reprovide"

# /api/v0/bitswap/stat

Show some diagnostic information on the bitswap agent.

# Arguments

verbose [bool]: Print extra information. Required: no.
human [bool]: Print sizes in human readable format (e.g., 1K 234M 2G). Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "BlocksReceived": "<uint64>",
  "BlocksSent": "<uint64>",
  "DataReceived": "<uint64>",
  "DataSent": "<uint64>",
  "DupBlksReceived": "<uint64>",
  "DupDataReceived": "<uint64>",
  "MessagesReceived": "<uint64>",
  "Peers": [
    "<string>"
  ],
  "ProvideBufLen": "<int>",
  "Wantlist": [
    {
      "/": "<cid-string>"
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/bitswap/stat?verbose=<value>&human=<value>"

# /api/v0/bitswap/wantlist

Show blocks currently on the wantlist.

# Arguments

peer [string]: Specify which peer to show wantlist for. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Keys": [
    {
      "/": "<cid-string>"
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/bitswap/wantlist?peer=<value>"

# /api/v0/block/get

Get a raw IPFS block.

# Arguments

arg [string]: The CID of an existing block to get. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/block/get?arg=<cid>"

# /api/v0/block/put

Store input as an IPFS block.

# Arguments

cid-codec [string]: Multicodec to use in returned CID. Default: raw. Required: no.
mhtype [string]: Multihash hash function. Default: sha2-256. Required: no.
mhlen [int]: Multihash hash length. Default: -1. Required: no.
pin [bool]: Pin added blocks recursively. Default: false. Required: no.
allow-big-block [bool]: Disable block size check and allow creation of blocks bigger than 1MiB. WARNING: such blocks won't be transferable over the standard bitswap. Default: false. Required: no.
format [string]: Use legacy format for returned CID (DEPRECATED). Required: no.

# Request Body

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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Key": "<string>",
  "Size": "<int>"
}

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/block/put?cid-codec=raw&mhtype=sha2-256&mhlen=-1&pin=false&allow-big-block=false&format=<value>"

# /api/v0/block/rm

Remove IPFS block(s) from the local datastore.

# Arguments

arg [string]: CIDs of block(s) to remove. Required: yes.
force [bool]: Ignore nonexistent blocks. Required: no.
quiet [bool]: Write minimal output. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Error": "<string>",
  "Hash": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/block/rm?arg=<cid>&force=<value>&quiet=<value>"

# /api/v0/block/stat

Print information of a raw IPFS block.

# Arguments

arg [string]: The CID of an existing block to stat. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Key": "<string>",
  "Size": "<int>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/block/stat?arg=<cid>"

# /api/v0/bootstrap

Show or edit the list of bootstrap peers.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Peers": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/bootstrap"

# /api/v0/bootstrap/add

Add peers to the bootstrap list.

# Arguments

arg [string]: A peer to add to the bootstrap list (in the format '<multiaddr>/<peerID>') Required: no.
default [bool]: Add default bootstrap nodes. (Deprecated, use 'default' subcommand instead). Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Peers": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/bootstrap/add?arg=<peer>&default=<value>"

# /api/v0/bootstrap/add/default

Add default peers to the bootstrap list.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Peers": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/bootstrap/add/default"

# /api/v0/bootstrap/list

Show peers in the bootstrap list.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Peers": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/bootstrap/list"

# /api/v0/bootstrap/rm

Remove peers from the bootstrap list.

# Arguments

arg [string]: A peer to add to the bootstrap list (in the format '<multiaddr>/<peerID>') Required: no.
all [bool]: Remove all bootstrap peers. (Deprecated, use 'all' subcommand). Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Peers": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/bootstrap/rm?arg=<peer>&all=<value>"

# /api/v0/bootstrap/rm/all

Remove all peers from the bootstrap list.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Peers": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/bootstrap/rm/all"

# /api/v0/cat

Show IPFS object data.

# Arguments

arg [string]: The path to the IPFS object(s) to be outputted. Required: yes.
offset [int64]: Byte offset to begin reading from. Required: no.
length [int64]: Maximum number of bytes to read. Required: no.
progress [bool]: Stream progress data. Default: true. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/cat?arg=<ipfs-path>&offset=<value>&length=<value>&progress=true"

# /api/v0/cid/base32

Convert CIDs to Base32 CID version 1.

# Arguments

arg [string]: CIDs to convert. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "CidStr": "<string>",
  "ErrorMsg": "<string>",
  "Formatted": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/cid/base32?arg=<cid>"

# /api/v0/cid/bases

List available multibase encodings.

# Arguments

prefix [bool]: also include the single letter prefixes in addition to the code. Required: no.
numeric [bool]: also include numeric codes. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

[
  {
    "Code": "<int>",
    "Name": "<string>"
  }
]

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/cid/bases?prefix=<value>&numeric=<value>"

# /api/v0/cid/codecs

List available CID multicodecs.

# Arguments

numeric [bool]: also include numeric codes. Required: no.
supported [bool]: list only codecs supported by go-ipfs commands. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

[
  {
    "Code": "<int>",
    "Name": "<string>"
  }
]

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/cid/codecs?numeric=<value>&supported=<value>"

# /api/v0/cid/format

Format and convert a CID in various useful ways.

# Arguments

arg [string]: CIDs to format. Required: yes.
f [string]: Printf style format string. Default: %s. Default: %s. Required: no.
v [string]: CID version to convert to. Required: no.
mc [string]: CID multicodec to convert to. Required: no.
b [string]: Multibase to display CID in. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "CidStr": "<string>",
  "ErrorMsg": "<string>",
  "Formatted": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/cid/format?arg=<cid>&f=%s&v=<value>&mc=<value>&b=<value>"

# /api/v0/cid/hashes

List available multihashes.

# Arguments

numeric [bool]: also include numeric codes. Required: no.
supported [bool]: list only codecs supported by go-ipfs commands. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

[
  {
    "Code": "<int>",
    "Name": "<string>"
  }
]

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/cid/hashes?numeric=<value>&supported=<value>"

# /api/v0/commands

List all available commands.

# Arguments

flags [bool]: Show command flags. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Name": "<string>",
  "Options": [
    {
      "Names": [
        "<string>"
      ]
    }
  ],
  "Subcommands": [
    {
      "Name": "<string>",
      "Options": [
        {
          "Names": [
            "<string>"
          ]
        }
      ],
      "Subcommands": [
        "..."
      ]
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/commands?flags=<value>"

# /api/v0/config

Get and set IPFS config values.

# Arguments

arg [string]: The key of the config entry (e.g. "Addresses.API"). Required: yes.
arg [string]: The value to set the config entry to. Required: no.
bool [bool]: Set a boolean value. Required: no.
json [bool]: Parse stringified JSON. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Key": "<string>",
  "Value": "<object>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/config?arg=<key>&arg=<value>&bool=<value>&json=<value>"

# /api/v0/config/profile/apply

Apply profile to config.

# Arguments

arg [string]: The profile to apply to the config. Required: yes.
dry-run [bool]: print difference between the current config and the config that would be generated. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "NewCfg": {
    "<string>": "<object>"
  },
  "OldCfg": {
    "<string>": "<object>"
  }
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/config/profile/apply?arg=<profile>&dry-run=<value>"

# /api/v0/config/replace

Replace the config with <file>.

# Arguments

# Request Body

Argument file 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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/config/replace"

# /api/v0/config/show

Output config file contents.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "<string>": "<object>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/config/show"

# /api/v0/dag/export

Streams the selected DAG as a .car stream on stdout.

# Arguments

arg [string]: CID of a root to recursively export Required: yes.
progress [bool]: Display progress on CLI. Defaults to true when STDERR is a TTY. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/dag/export?arg=<root>&progress=<value>"

# /api/v0/dag/get

Get a DAG node from IPFS.

# Arguments

arg [string]: The object to get Required: yes.
output-codec [string]: Format that the object will be encoded as. Default: dag-json. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/dag/get?arg=<ref>&output-codec=dag-json"

# /api/v0/dag/import

Import the contents of .car files

# Arguments

pin-roots [bool]: Pin optional roots listed in the .car headers after importing. Default: true. Required: no.
silent [bool]: No output. Required: no.
stats [bool]: Output stats. Required: no.
allow-big-block [bool]: Disable block size check and allow creation of blocks bigger than 1MiB. WARNING: such blocks won't be transferable over the standard bitswap. Default: false. Required: no.

# Request Body

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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Root": {
    "Cid": {
      "/": "<cid-string>"
    },
    "PinErrorMsg": "<string>"
  },
  "Stats": {
    "BlockBytesCount": "<uint64>",
    "BlockCount": "<uint64>"
  }
}

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/dag/import?pin-roots=true&silent=<value>&stats=<value>&allow-big-block=false"

# /api/v0/dag/put

Add a DAG node to IPFS.

# Arguments

store-codec [string]: Codec that the stored object will be encoded with. Default: dag-cbor. Required: no.
input-codec [string]: Codec that the input object is encoded in. Default: dag-json. Required: no.
pin [bool]: Pin this object when adding. Required: no.
hash [string]: Hash function to use. Default: sha2-256. Required: no.
allow-big-block [bool]: Disable block size check and allow creation of blocks bigger than 1MiB. WARNING: such blocks won't be transferable over the standard bitswap. Default: false. Required: no.

# Request Body

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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Cid": {
    "/": "<cid-string>"
  }
}

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/dag/put?store-codec=dag-cbor&input-codec=dag-json&pin=<value>&hash=sha2-256&allow-big-block=false"

# /api/v0/dag/resolve

Resolve IPLD block.

# Arguments

arg [string]: The path to resolve Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Cid": {
    "/": "<cid-string>"
  },
  "RemPath": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/dag/resolve?arg=<ref>"

# /api/v0/dag/stat

Gets stats for a DAG.

# Arguments

arg [string]: CID of a DAG root to get statistics for Required: yes.
progress [bool]: Return progressive data while reading through the DAG. Default: true. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "DagStats": [
    {
      "Cid": {
        "/": "<cid-string>"
      },
      "NumBlocks": "<int64>",
      "Size": "<uint64>"
    }
  ],
  "Ratio": "<float32>",
  "SharedSize": "<uint64>",
  "TotalSize": "<uint64>",
  "UniqueBlocks": "<int>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/dag/stat?arg=<root>&progress=true"

# /api/v0/dht/query

Find the closest Peer IDs to a given Peer ID by querying the DHT.

# Arguments

arg [string]: The peerID to run the query against. Required: yes.
verbose [bool]: Print extra information. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Extra": "<string>",
  "ID": "<peer-id>",
  "Responses": [
    {
      "Addrs": [
        "<multiaddr-string>"
      ],
      "ID": "peer-id"
    }
  ],
  "Type": "<int>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/dht/query?arg=<peerID>&verbose=<value>"

# /api/v0/diag/cmds

List commands run on this IPFS node.

# Arguments

verbose [bool]: Print extra information. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

[
  {
    "Active": "<bool>",
    "Args": [
      "<string>"
    ],
    "Command": "<string>",
    "EndTime": "<timestamp>",
    "ID": "<int>",
    "Options": {
      "<string>": "<object>"
    },
    "StartTime": "<timestamp>"
  }
]

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/diag/cmds?verbose=<value>"

# /api/v0/diag/cmds/clear

Clear inactive requests from the log.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/diag/cmds/clear"

# /api/v0/diag/cmds/set-time

Set how long to keep inactive requests in the log.

# Arguments

arg [string]: Time to keep inactive requests in log. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/diag/cmds/set-time?arg=<time>"

# /api/v0/diag/profile

Collect a performance profile for debugging.

# Arguments

output [string]: The path where the output .zip should be stored. Default: ./ipfs-profile-[timestamp].zip. Required: no.
collectors [array]: The list of collectors to use for collecting diagnostic data. Default: [goroutines-stack goroutines-pprof version heap allocs bin cpu mutex block]. Default: [goroutines-stack goroutines-pprof version heap allocs bin cpu mutex block]. Required: no.
profile-time [string]: The amount of time spent profiling. If this is set to 0, then sampling profiles are skipped. Default: 30s. Required: no.
mutex-profile-fraction [int]: The fraction 1/n of mutex contention events that are reported in the mutex profile. Default: 4. Required: no.
block-profile-rate [string]: The duration to wait between sampling goroutine-blocking events for the blocking profile. Default: 1ms. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/diag/profile?output=<value>&collectors=[goroutines-stack goroutines-pprof version heap allocs bin cpu mutex block]&profile-time=30s&mutex-profile-fraction=4&block-profile-rate=1ms"

# /api/v0/diag/sys

Print system diagnostic information.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/diag/sys"

# /api/v0/files/chcid

Change the CID version or hash function of the root node of a given path.

# Arguments

arg [string]: Path to change. Default: '/'. Required: no.
cid-version [int]: Cid version to use. (experimental). Required: no.
hash [string]: Hash function to use. Will set Cid version to 1 if used. (experimental). Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/files/chcid?arg=<path>&cid-version=<value>&hash=<value>"

# /api/v0/files/cp

Add references to IPFS files and directories in MFS (or copy within MFS).

# Arguments

arg [string]: Source IPFS or MFS path to copy. Required: yes.
arg [string]: Destination within MFS. Required: yes.
parents [bool]: Make parent directories as needed. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/files/cp?arg=<source>&arg=<dest>&parents=<value>"

# /api/v0/files/flush

Flush a given path's data to disk.

# Arguments

arg [string]: Path to flush. Default: '/'. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Cid": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/files/flush?arg=<path>"

# /api/v0/files/ls

List directories in the local mutable namespace.

# Arguments

arg [string]: Path to show listing for. Defaults to '/'. Required: no.
long [bool]: Use long listing format. Required: no.
U [bool]: Do not sort; list entries in directory order. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Entries": [
    {
      "Hash": "<string>",
      "Name": "<string>",
      "Size": "<int64>",
      "Type": "<int>"
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/files/ls?arg=<path>&long=<value>&U=<value>"

# /api/v0/files/mkdir

Make directories.

# Arguments

arg [string]: Path to dir to make. Required: yes.
parents [bool]: No error if existing, make parent directories as needed. Required: no.
cid-version [int]: Cid version to use. (experimental). Required: no.
hash [string]: Hash function to use. Will set Cid version to 1 if used. (experimental). Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/files/mkdir?arg=<path>&parents=<value>&cid-version=<value>&hash=<value>"

# /api/v0/files/mv

Move files.

# Arguments

arg [string]: Source file to move. Required: yes.
arg [string]: Destination path for file to be moved to. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/files/mv?arg=<source>&arg=<dest>"

# /api/v0/files/read

Read a file from MFS.

# Arguments

arg [string]: Path to file to be read. Required: yes.
offset [int64]: Byte offset to begin reading from. Required: no.
count [int64]: Maximum number of bytes to read. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/files/read?arg=<path>&offset=<value>&count=<value>"

# /api/v0/files/rm

Remove a file from MFS.

# Arguments

arg [string]: File to remove. Required: yes.
recursive [bool]: Recursively remove directories. Required: no.
force [bool]: Forcibly remove target at path; implies -r for directories. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/files/rm?arg=<path>&recursive=<value>&force=<value>"

# /api/v0/files/stat

Display file status.

# Arguments

arg [string]: Path to node to stat. Required: yes.
format [string]: Print statistics in given format. Allowed tokens: <hash> <size> <cumulsize> <type> <childs>. Conflicts with other format options. Default: <hash> Size: <size> CumulativeSize: <cumulsize> ChildBlocks: <childs> Type: <type>. Default: <hash> Size: <size> CumulativeSize: <cumulsize> ChildBlocks: <childs> Type: <type>. Required: no.
hash [bool]: Print only hash. Implies '--format=<hash>'. Conflicts with other format options. Required: no.
size [bool]: Print only size. Implies '--format=<cumulsize>'. Conflicts with other format options. Required: no.
with-local [bool]: Compute the amount of the dag that is local, and if possible the total size. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Blocks": "<int>",
  "CumulativeSize": "<uint64>",
  "Hash": "<string>",
  "Local": "<bool>",
  "Size": "<uint64>",
  "SizeLocal": "<uint64>",
  "Type": "<string>",
  "WithLocality": "<bool>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/files/stat?arg=<path>&format=<hash> Size: <size> CumulativeSize: <cumulsize> ChildBlocks: <childs> Type: <type>&hash=<value>&size=<value>&with-local=<value>"

# /api/v0/files/write

Append to (modify) a file in MFS.

# Arguments

arg [string]: Path to write to. Required: yes.
offset [int64]: Byte offset to begin writing at. Required: no.
create [bool]: Create the file if it does not exist. Required: no.
parents [bool]: Make parent directories as needed. Required: no.
truncate [bool]: Truncate the file to size zero before writing. Required: no.
count [int64]: Maximum number of bytes to read. Required: no.
raw-leaves [bool]: Use raw blocks for newly created leaf nodes. (experimental). Required: no.
cid-version [int]: Cid version to use. (experimental). Required: no.
hash [string]: Hash function to use. Will set Cid version to 1 if used. (experimental). Required: no.

# Request Body

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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/files/write?arg=<path>&offset=<value>&create=<value>&parents=<value>&truncate=<value>&count=<value>&raw-leaves=<value>&cid-version=<value>&hash=<value>"

# /api/v0/filestore/dups

List blocks that are both in the filestore and standard block storage.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Err": "<string>",
  "Ref": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/filestore/dups"

# /api/v0/filestore/ls

List objects in filestore.

# Arguments

arg [string]: Cid of objects to list. Required: no.
file-order [bool]: sort the results based on the path of the backing file. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "ErrorMsg": "<string>",
  "FilePath": "<string>",
  "Key": {
    "/": "<cid-string>"
  },
  "Offset": "<uint64>",
  "Size": "<uint64>",
  "Status": "<int32>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/filestore/ls?arg=<obj>&file-order=<value>"

# /api/v0/filestore/verify

Verify objects in filestore.

# Arguments

arg [string]: Cid of objects to verify. Required: no.
file-order [bool]: verify the objects based on the order of the backing file. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "ErrorMsg": "<string>",
  "FilePath": "<string>",
  "Key": {
    "/": "<cid-string>"
  },
  "Offset": "<uint64>",
  "Size": "<uint64>",
  "Status": "<int32>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/filestore/verify?arg=<obj>&file-order=<value>"

# /api/v0/get

Download IPFS objects.

# Arguments

arg [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 [bool]: Output a TAR archive. Required: no.
compress [bool]: Compress the output with GZIP compression. Required: no.
compression-level [int]: The level of compression (1-9). Required: no.
progress [bool]: Stream progress data. Default: true. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/get?arg=<ipfs-path>&output=<value>&archive=<value>&compress=<value>&compression-level=<value>&progress=true"

# /api/v0/id

Show IPFS node id info.

# Arguments

arg [string]: Peer.ID of node to look up. Required: no.
format [string]: Optional output format. Required: no.
peerid-base [string]: Encoding used for peer IDs: Can either be a multibase encoded CID or a base58btc encoded multihash. Takes {b58mh|base36|k|base32|b...}. Default: b58mh. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Addresses": [
    "<string>"
  ],
  "AgentVersion": "<string>",
  "ID": "<string>",
  "ProtocolVersion": "<string>",
  "Protocols": [
    "<string>"
  ],
  "PublicKey": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/id?arg=<peerid>&format=<value>&peerid-base=b58mh"

# /api/v0/key/gen

Create a new keypair

# Arguments

arg [string]: name of key to create Required: yes.
type [string]: type of the key to create: rsa, ed25519. Default: ed25519. Required: no.
size [int]: size of the key to generate. Required: no.
ipns-base [string]: Encoding used for keys: Can either be a multibase encoded CID or a base58btc encoded multihash. Takes {b58mh|base36|k|base32|b...}. Default: base36. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Id": "<string>",
  "Name": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/key/gen?arg=<name>&type=ed25519&size=<value>&ipns-base=base36"

# /api/v0/key/import

Import a key and prints imported key id

# Arguments

arg [string]: name to associate with key in keychain Required: yes.
ipns-base [string]: Encoding used for keys: Can either be a multibase encoded CID or a base58btc encoded multihash. Takes {b58mh|base36|k|base32|b...}. Default: base36. Required: no.
format [string]: The format of the private key to import, libp2p-protobuf-cleartext or pem-pkcs8-cleartext. Default: libp2p-protobuf-cleartext. Required: no.
allow-any-key-type [bool]: Allow importing any key type. Default: false. Required: no.

# Request Body

Argument key 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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Id": "<string>",
  "Name": "<string>"
}

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/key/import?arg=<name>&ipns-base=base36&format=libp2p-protobuf-cleartext&allow-any-key-type=false"

# /api/v0/key/list

List all local keypairs.

# Arguments

l [bool]: Show extra information about keys. Required: no.
ipns-base [string]: Encoding used for keys: Can either be a multibase encoded CID or a base58btc encoded multihash. Takes {b58mh|base36|k|base32|b...}. Default: base36. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Keys": [
    {
      "Id": "<string>",
      "Name": "<string>"
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/key/list?l=<value>&ipns-base=base36"

# /api/v0/key/rename

Rename a keypair.

# Arguments

arg [string]: name of key to rename Required: yes.
arg [string]: new name of the key Required: yes.
force [bool]: Allow to overwrite an existing key. Required: no.
ipns-base [string]: Encoding used for keys: Can either be a multibase encoded CID or a base58btc encoded multihash. Takes {b58mh|base36|k|base32|b...}. Default: base36. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Id": "<string>",
  "Now": "<string>",
  "Overwrite": "<bool>",
  "Was": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/key/rename?arg=<name>&arg=<newName>&force=<value>&ipns-base=base36"

# /api/v0/key/rm

Remove a keypair.

# Arguments

arg [string]: names of keys to remove Required: yes.
l [bool]: Show extra information about keys. Required: no.
ipns-base [string]: Encoding used for keys: Can either be a multibase encoded CID or a base58btc encoded multihash. Takes {b58mh|base36|k|base32|b...}. Default: base36. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Keys": [
    {
      "Id": "<string>",
      "Name": "<string>"
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/key/rm?arg=<name>&l=<value>&ipns-base=base36"

# /api/v0/log/level

Change the logging level.

# Arguments

arg [string]: The subsystem logging identifier. Use 'all' for all subsystems. Required: yes.
arg [string]: The log level, with 'debug' the most verbose and 'fatal' the least verbose. One of: debug, info, warn, error, dpanic, panic, fatal. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Message": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/log/level?arg=<subsystem>&arg=<level>"

# /api/v0/log/ls

List the logging subsystems.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Strings": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/log/ls"

# /api/v0/ls

List directory contents for Unix filesystem objects.

# Arguments

arg [string]: The path to the IPFS object(s) to list links from. Required: yes.
headers [bool]: Print table headers (Hash, Size, Name). Required: no.
resolve-type [bool]: Resolve linked objects to find out their types. Default: true. Required: no.
size [bool]: Resolve linked objects to find out their file size. Default: true. Required: no.
stream [bool]: Enable experimental streaming of directory entries as they are traversed. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Objects": [
    {
      "Hash": "<string>",
      "Links": [
        {
          "Hash": "<string>",
          "Name": "<string>",
          "Size": "<uint64>",
          "Target": "<string>",
          "Type": "<int32>"
        }
      ]
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/ls?arg=<ipfs-path>&headers=<value>&resolve-type=true&size=true&stream=<value>"

# /api/v0/multibase/decode

Decode multibase string

# Arguments

# Request Body

Argument encoded_file 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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/multibase/decode"

# /api/v0/multibase/encode

Encode data into multibase string

# Arguments

b [string]: multibase encoding. Default: base64url. Required: no.

# Request Body

Argument file 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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/multibase/encode?b=base64url"

# /api/v0/multibase/list

List available multibase encodings.

# Arguments

prefix [bool]: also include the single letter prefixes in addition to the code. Required: no.
numeric [bool]: also include numeric codes. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

[
  {
    "Code": "<int>",
    "Name": "<string>"
  }
]

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/multibase/list?prefix=<value>&numeric=<value>"

# /api/v0/multibase/transcode

Transcode multibase string between bases

# Arguments

b [string]: multibase encoding. Default: base64url. Required: no.

# Request Body

Argument encoded_file 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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/multibase/transcode?b=base64url"

# /api/v0/name/publish

Publish IPNS names.

# Arguments

arg [string]: ipfs path of the object to be published. Required: yes.
resolve [bool]: Check if the given path can be resolved before publishing. Default: true. Required: no.
lifetime [string]: Time duration that the record will be valid for. This accepts durations such as "300s", "1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". Default: 24h. Required: no.
allow-offline [bool]: When offline, save the IPNS record to the the local datastore without broadcasting to the network instead of simply failing. Required: no.
ttl [string]: Time duration this record should be cached for. Uses the same syntax as the lifetime option. (caution: experimental). Required: no.
key [string]: Name of the key to be used or a valid PeerID, as listed by 'ipfs key list -l'. Default: self. Required: no.
quieter [bool]: Write only final hash. Required: no.
ipns-base [string]: Encoding used for keys: Can either be a multibase encoded CID or a base58btc encoded multihash. Takes {b58mh|base36|k|base32|b...}. Default: base36. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Name": "<string>",
  "Value": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/name/publish?arg=<ipfs-path>&resolve=true&lifetime=24h&allow-offline=<value>&ttl=<value>&key=self&quieter=<value>&ipns-base=base36"

# /api/v0/name/resolve

Resolve IPNS names.

# Arguments

arg [string]: The IPNS name to resolve. Defaults to your node's peerID. Required: no.
recursive [bool]: Resolve until the result is not an IPNS name. Default: true. Required: no.
nocache [bool]: Do not use cached entries. Required: no.
dht-record-count [uint]: Number of records to request for DHT resolution. Required: no.
dht-timeout [string]: Max time to collect values during DHT resolution eg "30s". Pass 0 for no timeout. Required: no.
stream [bool]: Stream entries as they are found. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Path": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/name/resolve?arg=<name>&recursive=true&nocache=<value>&dht-record-count=<value>&dht-timeout=<value>&stream=<value>"

# /api/v0/pin/add

Pin objects to local storage.

# Arguments

arg [string]: Path to object(s) to be pinned. Required: yes.
recursive [bool]: Recursively pin the object linked to by the specified object(s). Default: true. Required: no.
progress [bool]: Show progress. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Pins": [
    "<string>"
  ],
  "Progress": "<int>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/pin/add?arg=<ipfs-path>&recursive=true&progress=<value>"

# /api/v0/pin/ls

List objects pinned to local storage.

# Arguments

arg [string]: Path to object(s) to be listed. Required: no.
type [string]: The type of pinned keys to list. Can be "direct", "indirect", "recursive", or "all". Default: all. Required: no.
quiet [bool]: Write just hashes of objects. Required: no.
stream [bool]: Enable streaming of pins as they are discovered. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "PinLsList": {
    "Keys": {
      "<string>": {
        "Type": "<string>"
      }
    }
  },
  "PinLsObject": {
    "Cid": "<string>",
    "Type": "<string>"
  }
}

# cURL Example

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

# /api/v0/pin/remote/add

Pin object to remote pinning service.

# Arguments

arg [string]: CID or Path to be pinned. Required: yes.
service [string]: Name of the remote pinning service to use (mandatory). Required: no.
name [string]: An optional name for the pin. Required: no.
background [bool]: Add to the queue on the remote service and return immediately (does not wait for pinned status). Default: false. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Cid": "<string>",
  "Name": "<string>",
  "Status": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/pin/remote/add?arg=<ipfs-path>&service=<value>&name=<value>&background=false"

# /api/v0/pin/remote/ls

List objects pinned to remote pinning service.

# Arguments

service [string]: Name of the remote pinning service to use (mandatory). Required: no.
name [string]: Return pins with names that contain the value provided (case-sensitive, exact match). Required: no.
cid [array]: Return pins for the specified CIDs (comma-separated). Required: no.
status [array]: Return pins with the specified statuses (queued,pinning,pinned,failed). Default: [pinned]. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Cid": "<string>",
  "Name": "<string>",
  "Status": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/pin/remote/ls?service=<value>&name=<value>&cid=<value>&status=[pinned]"

# /api/v0/pin/remote/rm

Remove pins from remote pinning service.

# Arguments

service [string]: Name of the remote pinning service to use (mandatory). Required: no.
name [string]: Remove pins with names that contain provided value (case-sensitive, exact match). Required: no.
cid [array]: Remove pins for the specified CIDs. Required: no.
status [array]: Remove pins with the specified statuses (queued,pinning,pinned,failed). Default: [pinned]. Required: no.
force [bool]: Allow removal of multiple pins matching the query without additional confirmation. Default: false. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/pin/remote/rm?service=<value>&name=<value>&cid=<value>&status=[pinned]&force=false"

# /api/v0/pin/remote/service/add

Add remote pinning service.

# Arguments

arg [string]: Service name. Required: yes.
arg [string]: Service endpoint. Required: yes.
arg [string]: Service key. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/pin/remote/service/add?arg=<service>&arg=<endpoint>&arg=<key>"

# /api/v0/pin/remote/service/ls

List remote pinning services.

# Arguments

stat [bool]: Try to fetch and display current pin count on remote service (queued/pinning/pinned/failed). Default: false. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "RemoteServices": [
    {
      "ApiEndpoint": "<string>",
      "Service": "<string>",
      "Stat": {
        "PinCount": {
          "Failed": "<int>",
          "Pinned": "<int>",
          "Pinning": "<int>",
          "Queued": "<int>"
        },
        "Status": "<string>"
      }
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/pin/remote/service/ls?stat=false"

# /api/v0/pin/remote/service/rm

Remove remote pinning service.

# Arguments

arg [string]: Name of remote pinning service to remove. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/pin/remote/service/rm?arg=<service>"

# /api/v0/pin/rm

Remove object from pin-list.

# Arguments

arg [string]: Path to object(s) to be unpinned. Required: yes.
recursive [bool]: Recursively unpin the object linked to by the specified object(s). Default: true. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Pins": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/pin/rm?arg=<ipfs-path>&recursive=true"

# /api/v0/pin/update

Update a recursive pin.

# Arguments

arg [string]: Path to old object. Required: yes.
arg [string]: Path to a new object to be pinned. Required: yes.
unpin [bool]: Remove the old pin. Default: true. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Pins": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/pin/update?arg=<from-path>&arg=<to-path>&unpin=true"

# /api/v0/pin/verify

Verify that recursive pins are complete.

# Arguments

verbose [bool]: Also write the hashes of non-broken pins. Required: no.
quiet [bool]: Write just hashes of broken pins. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Cid": "<string>",
  "Err": "<string>",
  "PinStatus": {
    "BadNodes": [
      {
        "Cid": "<string>",
        "Err": "<string>"
      }
    ],
    "Ok": "<bool>"
  }
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/pin/verify?verbose=<value>&quiet=<value>"

# /api/v0/ping

Send echo request packets to IPFS hosts.

# Arguments

arg [string]: ID of peer to be pinged. Required: yes.
count [int]: Number of ping messages to send. Default: 10. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Success": "<bool>",
  "Text": "<string>",
  "Time": "<duration-ns>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/ping?arg=<peer ID>&count=10"

# /api/v0/refs

List links (references) from an object.

# Arguments

arg [string]: Path to the object(s) to list refs from. Required: yes.
format [string]: Emit edges with given format. Available tokens: <src> <dst> <linkname>. Default: <dst>. Default: <dst>. Required: no.
edges [bool]: Emit edge format: <from> -> <to>. Required: no.
unique [bool]: Omit duplicate refs from output. Required: no.
recursive [bool]: Recursively list links of child nodes. Required: no.
max-depth [int]: Only for recursive refs, limits fetch and listing to the given depth. Default: -1. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Err": "<string>",
  "Ref": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/refs?arg=<ipfs-path>&format=<dst>&edges=<value>&unique=<value>&recursive=<value>&max-depth=-1"

# /api/v0/refs/local

List all local references.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Err": "<string>",
  "Ref": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/refs/local"

# /api/v0/repo/gc

Perform a garbage collection sweep on the repo.

# Arguments

stream-errors [bool]: Stream errors. Required: no.
quiet [bool]: Write minimal output. Required: no.
silent [bool]: Write no output. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Error": "<string>",
  "Key": {
    "/": "<cid-string>"
  }
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/repo/gc?stream-errors=<value>&quiet=<value>&silent=<value>"

# /api/v0/repo/ls

List all local references.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Err": "<string>",
  "Ref": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/repo/ls"

# /api/v0/repo/stat

Get stats for the currently used repo.

# Arguments

size-only [bool]: Only report RepoSize and StorageMax. Required: no.
human [bool]: Print sizes in human readable format (e.g., 1K 234M 2G). Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "NumObjects": "<uint64>",
  "RepoPath": "<string>",
  "SizeStat": {
    "RepoSize": "<uint64>",
    "StorageMax": "<uint64>"
  },
  "Version": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/repo/stat?size-only=<value>&human=<value>"

# /api/v0/repo/verify

Verify all blocks in repo are not corrupted.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Msg": "<string>",
  "Progress": "<int>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/repo/verify"

# /api/v0/repo/version

Show the repo version.

# Arguments

quiet [bool]: Write minimal output. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Version": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/repo/version?quiet=<value>"

# /api/v0/resolve

Resolve the value of names to IPFS.

# Arguments

arg [string]: The name to resolve. Required: yes.
recursive [bool]: Resolve until the result is an IPFS name. Default: true. Required: no.
dht-record-count [int]: Number of records to request for DHT resolution. Required: no.
dht-timeout [string]: Max time to collect values during DHT resolution eg "30s". Pass 0 for no timeout. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Path": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/resolve?arg=<name>&recursive=true&dht-record-count=<value>&dht-timeout=<value>"

# /api/v0/routing/findpeer

Find the multiaddresses associated with a Peer ID.

# Arguments

arg [string]: The ID of the peer to search for. Required: yes.
verbose [bool]: Print extra information. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Extra": "<string>",
  "ID": "<peer-id>",
  "Responses": [
    {
      "Addrs": [
        "<multiaddr-string>"
      ],
      "ID": "peer-id"
    }
  ],
  "Type": "<int>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/routing/findpeer?arg=<peerID>&verbose=<value>"

# /api/v0/routing/findprovs

Find peers that can provide a specific value, given a key.

# Arguments

arg [string]: The key to find providers for. Required: yes.
verbose [bool]: Print extra information. Required: no.
num-providers [int]: The number of providers to find. Default: 20. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Extra": "<string>",
  "ID": "<peer-id>",
  "Responses": [
    {
      "Addrs": [
        "<multiaddr-string>"
      ],
      "ID": "peer-id"
    }
  ],
  "Type": "<int>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/routing/findprovs?arg=<key>&verbose=<value>&num-providers=20"

# /api/v0/shutdown

Shut down the IPFS daemon.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/shutdown"

# /api/v0/stats/bitswap

Show some diagnostic information on the bitswap agent.

# Arguments

verbose [bool]: Print extra information. Required: no.
human [bool]: Print sizes in human readable format (e.g., 1K 234M 2G). Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "BlocksReceived": "<uint64>",
  "BlocksSent": "<uint64>",
  "DataReceived": "<uint64>",
  "DataSent": "<uint64>",
  "DupBlksReceived": "<uint64>",
  "DupDataReceived": "<uint64>",
  "MessagesReceived": "<uint64>",
  "Peers": [
    "<string>"
  ],
  "ProvideBufLen": "<int>",
  "Wantlist": [
    {
      "/": "<cid-string>"
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/stats/bitswap?verbose=<value>&human=<value>"

# /api/v0/stats/bw

Print IPFS bandwidth information.

# Arguments

peer [string]: Specify a peer to print bandwidth for. Required: no.
proto [string]: Specify a protocol to print bandwidth for. Required: no.
poll [bool]: Print bandwidth at an interval. Required: no.
interval [string]: Time interval to wait between updating output, if 'poll' is true.

This accepts durations such as "300s", "1.5h" or "2h45m". Valid time units are: "ns", "us" (or "µs"), "ms", "s", "m", "h". Default: 1s. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "RateIn": "<float64>",
  "RateOut": "<float64>",
  "TotalIn": "<int64>",
  "TotalOut": "<int64>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/stats/bw?peer=<value>&proto=<value>&poll=<value>&interval=1s"

# /api/v0/stats/dht

Returns statistics about the node's DHT(s).

# Arguments

arg [string]: The DHT whose table should be listed (wanserver, lanserver, wan, lan). wan and lan refer to client routing tables. When using the experimental DHT client only WAN is supported. Defaults to wan and lan. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Buckets": [
    {
      "LastRefresh": "<string>",
      "Peers": [
        {
          "AgentVersion": "<string>",
          "Connected": "<bool>",
          "ID": "<string>",
          "LastQueriedAt": "<string>",
          "LastUsefulAt": "<string>"
        }
      ]
    }
  ],
  "Name": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/stats/dht?arg=<dht>"

# /api/v0/stats/provide

Returns statistics about the node's (re)provider system.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "AvgProvideDuration": "<duration-ns>",
  "LastReprovideBatchSize": "<uint64>",
  "LastReprovideDuration": "<duration-ns>",
  "TotalProvides": "<uint64>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/stats/provide"

# /api/v0/stats/repo

Get stats for the currently used repo.

# Arguments

size-only [bool]: Only report RepoSize and StorageMax. Required: no.
human [bool]: Print sizes in human readable format (e.g., 1K 234M 2G). Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "NumObjects": "<uint64>",
  "RepoPath": "<string>",
  "SizeStat": {
    "RepoSize": "<uint64>",
    "StorageMax": "<uint64>"
  },
  "Version": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/stats/repo?size-only=<value>&human=<value>"

# /api/v0/swarm/addrs

List known addresses. Useful for debugging.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Addrs": {
    "<string>": [
      "<string>"
    ]
  }
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/swarm/addrs"

# /api/v0/swarm/addrs/listen

List interface listening addresses.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Strings": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/swarm/addrs/listen"

# /api/v0/swarm/addrs/local

List local addresses.

# Arguments

id [bool]: Show peer ID in addresses. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Strings": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/swarm/addrs/local?id=<value>"

# /api/v0/swarm/connect

Open connection to a given address.

# Arguments

arg [string]: Address of peer to connect to. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Strings": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/swarm/connect?arg=<address>"

# /api/v0/swarm/disconnect

Close connection to a given address.

# Arguments

arg [string]: Address of peer to disconnect from. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Strings": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/swarm/disconnect?arg=<address>"

# /api/v0/swarm/filters

Manipulate address filters.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Strings": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/swarm/filters"

# /api/v0/swarm/filters/add

Add an address filter.

# Arguments

arg [string]: Multiaddr to filter. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Strings": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/swarm/filters/add?arg=<address>"

# /api/v0/swarm/filters/rm

Remove an address filter.

# Arguments

arg [string]: Multiaddr filter to remove. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Strings": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/swarm/filters/rm?arg=<address>"

# /api/v0/swarm/peering/add

Add peers into the peering subsystem.

# Arguments

arg [string]: address of peer to add into the peering subsystem Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "ID": "<peer-id>",
  "Status": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/swarm/peering/add?arg=<address>"

# /api/v0/swarm/peering/ls

List peers registered in the peering subsystem.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Peers": [
    {
      "Addrs": [
        "<multiaddr-string>"
      ],
      "ID": "peer-id"
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/swarm/peering/ls"

# /api/v0/swarm/peering/rm

Remove a peer from the peering subsystem.

# Arguments

arg [string]: ID of peer to remove from the peering subsystem Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "ID": "<peer-id>",
  "Status": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/swarm/peering/rm?arg=<ID>"

# /api/v0/swarm/peers

List peers with open connections.

# Arguments

verbose [bool]: display all extra information. Required: no.
streams [bool]: Also list information about open streams for each peer. Required: no.
latency [bool]: Also list information about latency to each peer. Required: no.
direction [bool]: Also list information about the direction of connection. Required: no.
identify [bool]: Also list information about peers identify. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Peers": [
    {
      "Addr": "<string>",
      "Direction": "<int>",
      "Identify": {
        "Addresses": [
          "<string>"
        ],
        "AgentVersion": "<string>",
        "ID": "<string>",
        "ProtocolVersion": "<string>",
        "Protocols": [
          "<string>"
        ],
        "PublicKey": "<string>"
      },
      "Latency": "<string>",
      "Muxer": "<string>",
      "Peer": "<string>",
      "Streams": [
        {
          "Protocol": "<string>"
        }
      ]
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/swarm/peers?verbose=<value>&streams=<value>&latency=<value>&direction=<value>&identify=<value>"

# /api/v0/version

Show IPFS version information.

# Arguments

number [bool]: Only show the version number. Required: no.
commit [bool]: Show the commit hash. Required: no.
repo [bool]: Show repo version. Required: no.
all [bool]: Show all version information. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Commit": "<string>",
  "Golang": "<string>",
  "Repo": "<string>",
  "System": "<string>",
  "Version": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/version?number=<value>&commit=<value>&repo=<value>&all=<value>"

# /api/v0/version/deps

Shows information about dependencies used for build.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Path": "<string>",
  "ReplacedBy": "<string>",
  "Sum": "<string>",
  "Version": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/version/deps"

# Experimental RPC commands

Below commands are experimental and should be used with care. The API may change in future releases.

# /api/v0/log/tail

EXPERIMENTAL

This command is experimental.

Read the event log.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/log/tail"

# /api/v0/mount

EXPERIMENTAL

This command is experimental.

Mounts IPFS to the filesystem (read-only).

# Arguments

ipfs-path [string]: The path where IPFS should be mounted. Required: no.
ipns-path [string]: The path where IPNS should be mounted. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "FuseAllowOther": "<bool>",
  "IPFS": "<string>",
  "IPNS": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/mount?ipfs-path=<value>&ipns-path=<value>"

# /api/v0/name/inspect

EXPERIMENTAL

This command is experimental.

Inspects an IPNS Record

# Arguments

verify [string]: CID of the public IPNS key to validate against. Required: no.

# Request Body

Argument record 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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Entry": {
    "Data": "<object>",
    "PublicKey": "<string>",
    "Sequence": "<uint64>",
    "SignatureV1": "<string>",
    "SignatureV2": "<string>",
    "TTL": "<uint64>",
    "Validity": "<timestamp>",
    "ValidityType": "<int32>",
    "Value": "<string>"
  },
  "Validation": {
    "PublicKey": "<peer-id>",
    "Reason": "<string>",
    "Valid": "<bool>"
  }
}

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/name/inspect?verify=<value>"

# /api/v0/name/pubsub/cancel

EXPERIMENTAL

This command is experimental.

Cancel a name subscription.

# Arguments

arg [string]: Name to cancel the subscription for. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Canceled": "<bool>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/name/pubsub/cancel?arg=<name>"

# /api/v0/name/pubsub/state

EXPERIMENTAL

This command is experimental.

Query the state of IPNS pubsub.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Enabled": "<bool>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/name/pubsub/state"

# /api/v0/name/pubsub/subs

EXPERIMENTAL

This command is experimental.

Show current name subscriptions.

# Arguments

ipns-base [string]: Encoding used for keys: Can either be a multibase encoded CID or a base58btc encoded multihash. Takes {b58mh|base36|k|base32|b...}. Default: base36. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Strings": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/name/pubsub/subs?ipns-base=base36"

# /api/v0/p2p/close

EXPERIMENTAL

This command is experimental.

Stop listening for new connections to forward.

# Arguments

all [bool]: Close all listeners. Required: no.
protocol [string]: Match protocol name. Required: no.
listen-address [string]: Match listen address. Required: no.
target-address [string]: Match target address. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

"<int>"

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/p2p/close?all=<value>&protocol=<value>&listen-address=<value>&target-address=<value>"

# /api/v0/p2p/forward

EXPERIMENTAL

This command is experimental.

Forward connections to libp2p service.

# Arguments

arg [string]: Protocol name. Required: yes.
arg [string]: Listening endpoint. Required: yes.
arg [string]: Target endpoint. Required: yes.
allow-custom-protocol [bool]: Don't require /x/ prefix. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/p2p/forward?arg=<protocol>&arg=<listen-address>&arg=<target-address>&allow-custom-protocol=<value>"

# /api/v0/p2p/listen

EXPERIMENTAL

This command is experimental.

Create libp2p service.

# Arguments

arg [string]: Protocol name. Required: yes.
arg [string]: Target endpoint. Required: yes.
allow-custom-protocol [bool]: Don't require /x/ prefix. Required: no.
report-peer-id [bool]: Send remote base58 peerid to target when a new connection is established. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/p2p/listen?arg=<protocol>&arg=<target-address>&allow-custom-protocol=<value>&report-peer-id=<value>"

# /api/v0/p2p/ls

EXPERIMENTAL

This command is experimental.

List active p2p listeners.

# Arguments

headers [bool]: Print table headers (Protocol, Listen, Target). Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Listeners": [
    {
      "ListenAddress": "<string>",
      "Protocol": "<string>",
      "TargetAddress": "<string>"
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/p2p/ls?headers=<value>"

# /api/v0/p2p/stream/close

EXPERIMENTAL

This command is experimental.

Close active p2p stream.

# Arguments

arg [string]: Stream identifier Required: no.
all [bool]: Close all streams. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/p2p/stream/close?arg=<id>&all=<value>"

# /api/v0/p2p/stream/ls

EXPERIMENTAL

This command is experimental.

List active p2p streams.

# Arguments

headers [bool]: Print table headers (ID, Protocol, Local, Remote). Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Streams": [
    {
      "HandlerID": "<string>",
      "OriginAddress": "<string>",
      "Protocol": "<string>",
      "TargetAddress": "<string>"
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/p2p/stream/ls?headers=<value>"

# /api/v0/routing/get

EXPERIMENTAL

This command is experimental.

Given a key, query the routing system for its best value.

# Arguments

arg [string]: The key to find a value for. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Extra": "<string>",
  "ID": "<peer-id>",
  "Responses": [
    {
      "Addrs": [
        "<multiaddr-string>"
      ],
      "ID": "peer-id"
    }
  ],
  "Type": "<int>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/routing/get?arg=<key>"

# /api/v0/routing/provide

EXPERIMENTAL

This command is experimental.

Announce to the network that you are providing given values.

# Arguments

arg [string]: The key[s] to send provide records for. Required: yes.
verbose [bool]: Print extra information. Required: no.
recursive [bool]: Recursively provide entire graph. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Extra": "<string>",
  "ID": "<peer-id>",
  "Responses": [
    {
      "Addrs": [
        "<multiaddr-string>"
      ],
      "ID": "peer-id"
    }
  ],
  "Type": "<int>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/routing/provide?arg=<key>&verbose=<value>&recursive=<value>"

# /api/v0/routing/put

EXPERIMENTAL

This command is experimental.

Write a key/value pair to the routing system.

# Arguments

arg [string]: The key to store the value at. Required: yes.
allow-offline [bool]: When offline, save the IPNS record to the the local datastore without broadcasting to the network instead of simply failing. Required: no.

# Request Body

Argument value-file 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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Extra": "<string>",
  "ID": "<peer-id>",
  "Responses": [
    {
      "Addrs": [
        "<multiaddr-string>"
      ],
      "ID": "peer-id"
    }
  ],
  "Type": "<int>"
}

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/routing/put?arg=<key>&allow-offline=<value>"

# /api/v0/swarm/resources

EXPERIMENTAL

This command is experimental.

Get a summary of all resources accounted for by the libp2p Resource Manager.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

"<object>"

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/swarm/resources"

# Deprecated RPC commands

Below commands are deprecated and will be removed in the future.

# /api/v0/dht/findpeer

DEPRECATED

This command is deprecated.

Find the multiaddresses associated with a Peer ID.

# Arguments

arg [string]: The ID of the peer to search for. Required: yes.
verbose [bool]: Print extra information. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Extra": "<string>",
  "ID": "<peer-id>",
  "Responses": [
    {
      "Addrs": [
        "<multiaddr-string>"
      ],
      "ID": "peer-id"
    }
  ],
  "Type": "<int>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/dht/findpeer?arg=<peerID>&verbose=<value>"

# /api/v0/dht/findprovs

DEPRECATED

This command is deprecated.

Find peers that can provide a specific value, given a key.

# Arguments

arg [string]: The key to find providers for. Required: yes.
verbose [bool]: Print extra information. Required: no.
num-providers [int]: The number of providers to find. Default: 20. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Extra": "<string>",
  "ID": "<peer-id>",
  "Responses": [
    {
      "Addrs": [
        "<multiaddr-string>"
      ],
      "ID": "peer-id"
    }
  ],
  "Type": "<int>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/dht/findprovs?arg=<key>&verbose=<value>&num-providers=20"

# /api/v0/dht/get

DEPRECATED

This command is deprecated.

Given a key, query the routing system for its best value.

# Arguments

arg [string]: The key to find a value for. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Extra": "<string>",
  "ID": "<peer-id>",
  "Responses": [
    {
      "Addrs": [
        "<multiaddr-string>"
      ],
      "ID": "peer-id"
    }
  ],
  "Type": "<int>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/dht/get?arg=<key>"

# /api/v0/dht/provide

DEPRECATED

This command is deprecated.

Announce to the network that you are providing given values.

# Arguments

arg [string]: The key[s] to send provide records for. Required: yes.
verbose [bool]: Print extra information. Required: no.
recursive [bool]: Recursively provide entire graph. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Extra": "<string>",
  "ID": "<peer-id>",
  "Responses": [
    {
      "Addrs": [
        "<multiaddr-string>"
      ],
      "ID": "peer-id"
    }
  ],
  "Type": "<int>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/dht/provide?arg=<key>&verbose=<value>&recursive=<value>"

# /api/v0/dht/put

DEPRECATED

This command is deprecated.

Write a key/value pair to the routing system.

# Arguments

arg [string]: The key to store the value at. Required: yes.
allow-offline [bool]: When offline, save the IPNS record to the the local datastore without broadcasting to the network instead of simply failing. Required: no.

# Request Body

Argument value-file 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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Extra": "<string>",
  "ID": "<peer-id>",
  "Responses": [
    {
      "Addrs": [
        "<multiaddr-string>"
      ],
      "ID": "peer-id"
    }
  ],
  "Type": "<int>"
}

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/dht/put?arg=<key>&allow-offline=<value>"

# /api/v0/dns

DEPRECATED

This command is deprecated.

Resolve DNSLink records.

# Arguments

arg [string]: The domain-name name to resolve. Required: yes.
recursive [bool]: Resolve until the result is not a DNS link. Default: true. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Path": "<string>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/dns?arg=<domain-name>&recursive=true"

# /api/v0/file/ls

DEPRECATED

This command is deprecated.

List directory contents for Unix filesystem objects. Deprecated: Use 'ipfs ls' and 'ipfs files ls' instead.

# Arguments

arg [string]: The path to the IPFS object(s) to list links from. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Arguments": {
    "<string>": "<string>"
  },
  "Objects": {
    "<string>": {
      "Hash": "<string>",
      "Links": [
        {
          "Hash": "<string>",
          "Name": "<string>",
          "Size": "<uint64>",
          "Type": "<string>"
        }
      ],
      "Size": "<uint64>",
      "Type": "<string>"
    }
  }
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/file/ls?arg=<ipfs-path>"

# /api/v0/object/data

DEPRECATED

This command is deprecated.

Deprecated way to read the raw bytes of a dag-pb object: use 'dag get' instead.

# Arguments

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

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/object/data?arg=<key>"

# /api/v0/object/diff

DEPRECATED

This command is deprecated.

Display the diff between two IPFS objects.

# Arguments

arg [string]: Object to diff against. Required: yes.
arg [string]: Object to diff. Required: yes.
verbose [bool]: Print extra information. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Changes": [
    {
      "After": {
        "/": "<cid-string>"
      },
      "Before": {
        "/": "<cid-string>"
      },
      "Path": "<string>",
      "Type": "<int>"
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/object/diff?arg=<obj_a>&arg=<obj_b>&verbose=<value>"

# /api/v0/object/get

DEPRECATED

This command is deprecated.

Deprecated way to get and serialize the dag-pb node. Use 'dag get' instead

# Arguments

arg [string]: Key of the dag-pb object to retrieve, in base58-encoded multihash format. Required: yes.
data-encoding [string]: Encoding type of the data field, either "text" or "base64". Default: text. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Data": "<string>",
  "Links": [
    {
      "Hash": "<string>",
      "Name": "<string>",
      "Size": "<uint64>"
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/object/get?arg=<key>&data-encoding=text"

# /api/v0/object/links

DEPRECATED

This command is deprecated.

Deprecated way to output links in the specified dag-pb object: use 'dag get' instead.

# Arguments

arg [string]: Key of the dag-pb object to retrieve, in base58-encoded multihash format. Required: yes.
headers [bool]: Print table headers (Hash, Size, Name). Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Hash": "<string>",
  "Links": [
    {
      "Hash": "<string>",
      "Name": "<string>",
      "Size": "<uint64>"
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/object/links?arg=<key>&headers=<value>"

# /api/v0/object/new

DEPRECATED

This command is deprecated.

Deprecated way to create a new dag-pb object from a template.

# Arguments

arg [string]: Template to use. Optional. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Hash": "<string>",
  "Links": [
    {
      "Hash": "<string>",
      "Name": "<string>",
      "Size": "<uint64>"
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/object/new?arg=<template>"

# /api/v0/object/patch/add-link

DEPRECATED

This command is deprecated.

Deprecated way to add a link to a given dag-pb.

# Arguments

arg [string]: The hash of the node to modify. Required: yes.
arg [string]: Name of link to create. Required: yes.
arg [string]: IPFS object to add link to. Required: yes.
create [bool]: Create intermediary nodes. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Hash": "<string>",
  "Links": [
    {
      "Hash": "<string>",
      "Name": "<string>",
      "Size": "<uint64>"
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/object/patch/add-link?arg=<root>&arg=<name>&arg=<ref>&create=<value>"

# /api/v0/object/patch/append-data

DEPRECATED

This command is deprecated.

Deprecated way to append data to the data segment of a DAG node.

# Arguments

arg [string]: The hash of the node to modify. Required: yes.

# Request Body

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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Hash": "<string>",
  "Links": [
    {
      "Hash": "<string>",
      "Name": "<string>",
      "Size": "<uint64>"
    }
  ]
}

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/object/patch/append-data?arg=<root>"

# /api/v0/object/patch/rm-link

DEPRECATED

This command is deprecated.

Deprecated way to remove a link from dag-pb object.

# Arguments

arg [string]: The hash of the node to modify. Required: yes.
arg [string]: Name of the link to remove. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Hash": "<string>",
  "Links": [
    {
      "Hash": "<string>",
      "Name": "<string>",
      "Size": "<uint64>"
    }
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/object/patch/rm-link?arg=<root>&arg=<name>"

# /api/v0/object/patch/set-data

DEPRECATED

This command is deprecated.

Deprecated way to set the data field of dag-pb object.

# Arguments

arg [string]: The hash of the node to modify. Required: yes.

# Request Body

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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Hash": "<string>",
  "Links": [
    {
      "Hash": "<string>",
      "Name": "<string>",
      "Size": "<uint64>"
    }
  ]
}

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/object/patch/set-data?arg=<root>"

# /api/v0/object/put

DEPRECATED

This command is deprecated.

Deprecated way to store input as a DAG object. Use 'dag put' instead.

# Arguments

inputenc [string]: Encoding type of input data. One of: {"protobuf", "json"}. Default: json. Required: no.
datafieldenc [string]: Encoding type of the data field, either "text" or "base64". Default: text. Required: no.
pin [bool]: Pin this object when adding. Required: no.
quiet [bool]: Write minimal output. Required: no.

# Request Body

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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Hash": "<string>",
  "Links": [
    {
      "Hash": "<string>",
      "Name": "<string>",
      "Size": "<uint64>"
    }
  ]
}

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/object/put?inputenc=json&datafieldenc=text&pin=<value>&quiet=<value>"

# /api/v0/object/stat

DEPRECATED

This command is deprecated.

Deprecated way to read stats for the dag-pb node. Use 'files stat' instead.

# Arguments

arg [string]: Key of the object to retrieve, in base58-encoded multihash format. Required: yes.
human [bool]: Print sizes in human readable format (e.g., 1K 234M 2G). Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "BlockSize": "<int>",
  "CumulativeSize": "<int>",
  "DataSize": "<int>",
  "Hash": "<string>",
  "LinksSize": "<int>",
  "NumLinks": "<int>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/object/stat?arg=<key>&human=<value>"

# /api/v0/pubsub/ls

DEPRECATED

This command is deprecated.

List subscribed topics by name.

# Arguments

This endpoint takes no arguments.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Strings": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/pubsub/ls"

# /api/v0/pubsub/peers

DEPRECATED

This command is deprecated.

List peers we are currently pubsubbing with.

# Arguments

arg [string]: Topic to list connected peers of. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Strings": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/pubsub/peers?arg=<topic>"

# /api/v0/pubsub/pub

DEPRECATED

This command is deprecated.

Publish data to a given pubsub topic.

# Arguments

arg [string]: Topic to publish to (multibase encoded when sent over HTTP RPC). Required: yes.

# Request Body

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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/pubsub/pub?arg=<topic>"

# /api/v0/pubsub/sub

DEPRECATED

This command is deprecated.

Subscribe to messages on a given topic.

# Arguments

arg [string]: Name of topic to subscribe to (multibase encoded when sent over HTTP RPC). Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "data": "<string>",
  "from": "<string>",
  "seqno": "<string>",
  "topicIDs": [
    "<string>"
  ]
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/pubsub/sub?arg=<topic>"

# /api/v0/tar/add

DEPRECATED

This command is deprecated.

Import a tar file into IPFS.

# Arguments

# Request Body

Argument file 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'.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Bytes": "<int64>",
  "Hash": "<string>",
  "Name": "<string>",
  "Size": "<string>"
}

# cURL Example

curl -X POST -F file=@myfile "http://127.0.0.1:5001/api/v0/tar/add"

# /api/v0/tar/cat

DEPRECATED

This command is deprecated.

Export a tar file from IPFS.

# Arguments

arg [string]: ipfs path of archive to export. Required: yes.

# Response

On success, the call to this endpoint will return with 200 and the following body:

This endpoint returns a `text/plain` response body.

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/tar/cat?arg=<path>"

# /api/v0/urlstore/add

DEPRECATED

This command is deprecated.

Add URL via urlstore.

# Arguments

arg [string]: URL to add to IPFS Required: yes.
trickle [bool]: Use trickle-dag format for dag generation. Required: no.
pin [bool]: Pin this object when adding. Default: true. Required: no.

# Response

On success, the call to this endpoint will return with 200 and the following body:

{
  "Key": "<string>",
  "Size": "<int>"
}

# cURL Example

curl -X POST "http://127.0.0.1:5001/api/v0/urlstore/add?arg=<url>&trickle=<value>&pin=true"

Was this information helpful?

Edit this page on GitHub or open an issue

Help us improve this site!

Suggest new content

Give general feedback