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

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

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

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

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

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

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

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

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

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

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

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

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

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

Status codes used at the RPC layer are simple:

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

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

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

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