Permalink
Fetching contributors…
Cannot retrieve contributors at this time
12591 lines (8997 sloc) 300 KB
FORMAT: 1A
# IPFS
The API for interacting with IPFS nodes.
The HTTP API is currently accepting all methods, so GET will work just as well as POST for any group. Because of this, the methods shown below are the specifications that should be adhered to, although any will work. For more, see this discussion: https://github.com/ipfs/go-ipfs/issues/2165.
# Group add
Add a file or directory to IPFS.
## add [POST /add{?arg}{&r,p,t,n,w,H,s,pin}]
#### curl
curl -F "file=@test" "http://localhost:5001/api/v0/add"
+ Parameters
+ arg (string, required) - The path to a file to be added to IPFS.
+ H (boolean, optional) - Hidden. Include files that are hidden. Default: false.
+ n (boolean, optional) - Only-hash. Only chunk and hash - do not write to disk. Default: false.
+ p (boolean, optional) - Progress. Stream progress data. Default: true.
+ pin (boolean, optional) - Pin this object when adding. Default: true.
+ r (boolean, optional) - Recursive. Add directory paths recursively. Default: false.
+ s (boolean, optional) - Chunker. Chunking algorithm to use.
+ t (boolean, optional) - Trickle. Use trickle-dag format for dag generation. Default: false.
+ w (boolean, optional) - Wrap-with-directory. Wrap files with a directory object. Default: false.
+ Request Single File (multipart/form-data; boundary=CUSTOM)
#### Curl
curl -i -H "Content-Type: multipart/form-data; boundary=CUSTOM" -d $'--CUSTOM\r\nContent-Type: multipart/octet-stream\r\nContent-Disposition: file; filename="test"\r\n\r\nHello World!\n--CUSTOM--' "http://localhost:5001/api/v0/add"
+ Body
```
curl -i -H "Content-Type: multipart/form-data; boundary=CUSTOM" -d $'--CUSTOM\r\nContent-Type: multipart/octet-stream\r\nContent-Disposition: file; filename="test"\r\n\r\nHello World!\n--CUSTOM--' "http://localhost:5001/api/v0/add"
```
+ Response 200
Note that the response sends a 100 continuation code before a 200 code.
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
X-Chunked-Output: 1
Date: Thu, 28 Apr 2016 17:36:50 GMT
Transfer-Encoding: chunked
```
+ Attributes
+ Name (string)
+ Hash (Multihash)
+ Body
```
{
"Name":"test",
"Hash":"QmfM2r8seH2GiRaC4esTjeraXEachRt8ZsSeGaWTPLyMoG"
}
```
+ Request Progress (multipart/form-data)
#### Curl
curl -i -F "file=@test" "http://localhost:5001/api/v0/add?p"
+ Body
```
curl -i -F "file=@test" "http://localhost:5001/api/v0/add?p"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
X-Chunked-Output: 1
Date: Thu, 28 Apr 2016 17:37:07 GMT
Transfer-Encoding: chunked
```
+ Attributes (ndjson)
+ Object (object)
- Name: test/test (string)
- Bytes: 12 (number)
+ Object (object)
- Name: test/test (string)
- Hash (Multihash)
+ Body
```
{
"Name": "test",
"Bytes": 12
}
{
"Name": "test",
"Hash": "QmePw8gVcBMb8x6kAep6aMBAX23hCSk6iZW3i9VKkiFhu1"
}
```
+ Request Trickle (multipart/form-data)
#### Curl
curl -i -F "file=@test" "http://localhost:5001/api/v0/add?t"
+ Body
```
curl -i -F "file=@test" "http://localhost:5001/api/v0/add?t"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
X-Chunked-Output: 1
Date: Thu, 28 Apr 2016 17:37:21 GMT
Transfer-Encoding: chunked
```
+ Attributes (ndjson)
+ Object (object)
- Name: test/test (string)
- Hash (Multihash)
+ Body
```
{
"Name": "test",
"Hash": "QmePw8gVcBMb8x6kAep6aMBAX23hCSk6iZW3i9VKkiFhu1"
}
```
+ Request Only Hash (multipart/form-data)
#### Curl
curl -i -F "file=@test" "http://localhost:5001/api/v0/add?n"
+ Body
```
curl -i -F "file=@test" "http://localhost:5001/api/v0/add?n"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
X-Chunked-Output: 1
Date: Thu, 28 Apr 2016 17:37:33 GMT
Transfer-Encoding: chunked
```
+ Attributes (ndjson)
+ Object (object)
- Name: test/test (string)
- Hash (Multihash)
+ Body
```
{
"Name": "test",
"Bytes": 12
}
{
"Name": "test",
"Hash": "QmePw8gVcBMb8x6kAep6aMBAX23hCSk6iZW3i9VKkiFhu1"
}
```
+ Request Wrap with Directory (multipart/form-data)
#### Curl
curl -i -F "file=@test" "http://localhost:5001/api/v0/add?w"
+ Body
```
curl -i -F "file=@test" "http://localhost:5001/api/v0/add?w"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
X-Chunked-Output: 1
Date: Thu, 28 Apr 2016 17:37:46 GMT
Transfer-Encoding: chunked
```
+ Attributes (ndjson)
+ Object (object)
- Name: test/test (string)
- Hash (Multihash)
+ Body
```
{
"Name": "test",
"Hash": "QmePw8gVcBMb8x6kAep6aMBAX23hCSk6iZW3i9VKkiFhu1"
}
{
"Name": "",
"Hash": "QmV7sQezAjKh9pokjUPLL7ebuMF5t56UmfhK4cJncCcrNZ"
}
```
+ Request Hidden (multipart/form-data)
#### Curl
curl -i -F "file=@test" "http://localhost:5001/api/v0/add?H"
+ Body
```
curl -i -F "file=@test" "http://localhost:5001/api/v0/add?H"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
X-Chunked-Output: 1
Date: Thu, 28 Apr 2016 17:37:59 GMT
Transfer-Encoding: chunked
```
+ Attributes (ndjson)
+ Object (object)
- Name: test/test (string)
- Hash (Multihash)
+ Body
```
{
"Name": "test",
"Hash": "QmePw8gVcBMb8x6kAep6aMBAX23hCSk6iZW3i9VKkiFhu1"
}
```
+ Request Chunker (multipart/form-data)
#### Curl
curl -i -F "file=@test" "http://localhost:5001/api/v0/add?s"
+ Body
```
curl -i -F "file=@test" "http://localhost:5001/api/v0/add?s"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
X-Chunked-Output: 1
Date: Thu, 28 Apr 2016 17:38:11 GMT
Transfer-Encoding: chunked
```
+ Attributes (ndjson)
+ Object (object)
- Name: test/test (string)
- Hash (Multihash)
+ Body
```
{
"Name": "test",
"Hash": "QmePw8gVcBMb8x6kAep6aMBAX23hCSk6iZW3i9VKkiFhu1"
}
```
+ Request Recursive (multipart/form-data)
#### Curl
curl -i -F "file=@test" "http://localhost:5001/api/v0/add?r"
+ Body
```
curl -i -F "file=@test" "http://localhost:5001/api/v0/add?r"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
X-Chunked-Output: 1
Date: Thu, 28 Apr 2016 17:40:06 GMT
Transfer-Encoding: chunked
```
+ Attributes (ndjson)
+ Object (object)
- Name: test/test (string)
- Bytes: 12 (number)
+ Object (object)
- Name: test/test (string)
- Hash (Multihash)
+ Body
```
{
"Name": "test/test",
"Bytes": 12
}
{
"Name": "test/test",
"Hash": "QmePw8gVcBMb8x6kAep6aMBAX23hCSk6iZW3i9VKkiFhu1"
}
{
"Name": "test",
"Hash": "QmV7sQezAjKh9pokjUPLL7ebuMF5t56UmfhK4cJncCcrNZ"
}
```
+ Request Empty Arguments
#### curl
curl -i "http://localhost:5001/api/v0/add"
+ Body
```
curl -i "http://localhost:5001/api/v0/add"
```
+ Response 400
+ Headers
```
Date: Fri, 08 Jan 2016 15:22:01 GMT
Content-Length: 32
Content-Type: text/plain; charset=utf-8
```
+ Body
```
File argument `path` is required
```
# Group bitswap
A set of commands to manipulate the bitswap agent.
This command can't be called directly.
## stat [GET /bitswap/stat]
Show some diagnostic information on the bitswap agent.
+ Request
#### curl
curl -i http://localhost:5001/api/v0/bitswap/stat
+ Body
```
curl -i http://localhost:5001/api/v0/bitswap/stat
```
+ Response 200
+ Attributes (object)
+ ProvideBufLen: 0 (number)
+ Wantlist (array, nullable)
+ Peers (array)
- QmNjRVohhWBX31EoaAXkrj5mPF9vQNcTVvQgWHNwdxweCN (Multihash)
+ BlocksReceived: 0 (number)
+ DupBlksReceived: 0 (number)
+ DupDataReceived: 0 (number)
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.2
Trailer: X-Stream-Error
Vary: Origin
Date: Mon, 13 Jun 2016 11:06:46 GMT
Transfer-Encoding: chunked
```
+ Body
```
{
"ProvideBufLen": 0,
"Wantlist": null,
"Peers": [
"QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM",
"QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z",
"QmSoLueR4xBeUbY9WZ9xGUUxunbKWcrNFTDAadQJmocnWm"
],
"BlocksReceived": 0,
"DupBlksReceived": 0,
"DupDataReceived": 0
}
```
## unwant [GET /bitswap/unwant{?arg*}]
Remove a given block from your wantlist.
+ Parameters
+ arg (Multihash, required) - Key or keys to remove from your wantlist.
+ Request With No Arguments
#### curl
curl -i http://localhost:5001/api/v0/bitswap/unwant
+ Body
```
curl -i http://localhost:5001/api/v0/bitswap/unwant
```
+ Response 400
+ Headers
```
Date: Fri, 29 Jan 2016 20:25:10 GMT
Content-Length: 26
Content-Type: text/plain; charset=utf-8
```
+ Body
```
Argument 'key' is required
```
+ Request Empty Argument
#### curl
curl -i http://localhost:5001/api/v0/bitswap/unwant?arg=
+ Body
```
curl -i http://localhost:5001/api/v0/bitswap/unwant?arg=
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 17:50:44 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: 'incorrectly formatted key: '
- Code: 0
+ Body
```
{
"Message": "Incorrectly formatted key: ",
"Code": 0
}
```
+ Request With Invalid Argument
#### curl
curl -i http://localhost:5001/api/v0/bitswap/unwant?arg=kitten
+ Body
```
curl -i http://localhost:5001/api/v0/bitswap/unwant?arg=kitten
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 17:50:33 GMT
Transfer-Encoding: chunked
```
+ Attributes
+ Body
```
```
+ Request With Key
#### curl
curl -i http://localhost:5001/api/v0/bitswap/unwant?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ
+ Body
```
curl -i http://localhost:5001/api/v0/bitswap/unwant?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 17:51:00 GMT
Transfer-Encoding: chunked
```
+ Body
```
```
+ Request With Multiple Keys
#### curl
curl -i http://localhost:5001/api/v0/bitswap/unwant?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ&arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ
+ Body
```
curl -i http://localhost:5001/api/v0/bitswap/unwant?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ&arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 17:51:10 GMT
Transfer-Encoding: chunked
```
+ Body
```
```
## wantlist [GET /bitswap/wantlist{?peer}]
Show blocks currently on the wantlist.
Print out all blocks currently on the bitswap wantlist for the local peer.
+ Parameters
+ peer (Multihash, optional) - Specify which peer to show wantlist for. Default: self.
+ Request No Arguments
#### curl
curl -i http://localhost:5001/api/v0/bitswap/wantlist
+ Body
```
curl -i http://localhost:5001/api/v0/bitswap/wantlist
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 17:48:53 GMT
Transfer-Encoding: chunked
```
+ Attributes
+ Keys (array) - The keys
+ Body
```
{
"Keys": null
}
```
+ Request with Invalid Argument
The response is the same if the argument is not included. For example:
curl -i http://localhost:5001/api/v0/bitswap/wantlist?peer=
#### curl
curl -i http://localhost:5001/api/v0/bitswap/wantlist?peer=cat.jpg
+ Body
```
curl -i http://localhost:5001/api/v0/bitswap/wantlist?peer=cat.jpg
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 17:49:04 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: 'multihash too short. must be \u003e 3 bytes'
- Code: 0
+ Body
```
{
"Message": "multihash too short. must be \u003e 3 bytes",
"Code": 0
}
```
+ Request With Peer
#### curl
curl -i http://localhost:5001/api/v0/bitswap/wantlist?peer=QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM
+ Body
```
curl -i http://localhost:5001/api/v0/bitswap/wantlist?peer=QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 17:49:15 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
+ Keys (array)
- (Multihash)
+ Body
```
{
"Keys": [
"QmeQh6xVvGEKEkeKVEAUg6svnLogNxNBMHnEeEyvw8yfsd",
"QmZe4oTtfmQKmzwVob8N5MUSw1zcwW44J46sV3vjTa29TV",
"QmS8wN8cBMdASH7cEpCbVGXiK5kvD1Rz7cYgShs18mFCbh",
"QmQeKw6b6fJ48ett5JMsVDmQTqEimwtSEWAtnGAvAEdb5W",
"QmSuX7yWDSZM2rns2PtSz1r6n5C6XoU1EvE5DaUsnpeMCm",
"QmRUctQmvs3M8EUUG8G1srJm4PLqD6x9719zm1nAPYRKv8",
"QmX14SaE4U7dTavWDVXviBToXji65haa8KHHYAnDJ8x7Ci",
"QmNrE6csRAHZUYA1mPyszpx9sYEzgSoi2SpBrPhZDRAhv1",
"QmXKzXvbmLZ7v1Ns8oFBxNujHoRBDCgtYVyiF9YEyeo5dC",
"QmaY7qHWpdQJ9QcTmrrgHL4ykAABULrZkvSUCCLTb79iS5",
"QmYbmoDHDNgqoDbLC4vMyoMH5dYQdrxL1wh63x9rhSC6Zf",
"QmcXMzFwmhDciqAfFemVpaFyEs3Kz7TABs7ARMtt1qRpxj",
"QmShCGUPPASXFTBJGUAbyfkUy3ntQxuy4FUSupV1UjRqk6",
"QmQwR1UZTxDz2T8qdZBCC5qTvLZnnPrWp2LvtdkKUPhsyh",
"QmPFVbtH6Dqf35Rc4UFkTcrFkPrTym7KS1RqVcA6gv8uMq",
"QmWBFyiMbJxSsmaudS7rQnt6tkDFrbDYjkVpsjLUT8bwqS",
"QmXth7PrfapKZmC3GE7kucQWCBgXqyYHeDRLibmBaCK5wq",
"QmWSHWupzYH2ZrC8teiYQATUC14go7Gx9k7GYXrdwuLnFr",
"Qmamu7JPzTFnyUcpo2qSuEpsFkYEnewCcU2PixQ3v7QCr1",
"QmbZdk1SKmTg2ivwyqoHjRMUi4WTkF9sZfDx6hyjJGMU5a",
"QmbL6gjKM1LPBEgqAoDUvKAHdp1zAAkeD78UZS4BSLwJCY",
"QmSFZZEu5SF4Yes1YLvuQyU5LK1in2knq5dma9Dd2ezjy2",
"QmRpiFpFuzaQvuSbukUzZUB6BjzFKCMYK4saaJvsMSo1Ab",
"QmPBrnRNZvidUzWT4NkvhGfJwCzfNk1WFvBF4PYh1rW9de",
"QmP4FJ4jyk9TDcuUzMbtCThSraAj3FKC9q6LLMDfPTtnqF",
"QmR1kZwr4zrrkVMjtNrZSZNAP7btbNNhUCDzFn7vjytQWU",
"QmVRvtjmWLpMphqAj9k1bySbZTUN2C9sZ64JUrh9wanLj5",
"QmbeQDMbw8cdvyBZ9BsKTWfe2iXUbSXBc5FY9EqFfFgY2Q",
"QmZsTuTBFzveqUWyE3K7LPrLeTEaquyNU7YQbYfqQfJNLp",
"QmTBKAHg6VFnNkn2bBvi4Uk9CpTDpxEKUm5BsbjXcuwARw",
"Qmd38Q7j9pczrWZ9M1jZEoX4xx6E8E41w2dEbud3KYv2YX"
]
}
```
# Group block
Manipulate raw IPFS blocks.
This command can't be called directly.
## get [GET /block/get{?arg}]
Store data as a raw ipfs block.
+ Parameters
+ arg (Multihash, required) - The base58 multihash of an existing block to get.
+ Request No Arguments
#### curl
curl -i "http://localhost:5001/api/v0/block/get"
+ Body
```
curl -i "http://localhost:5001/api/v0/block/get"
```
+ Response 400
+ Headers
```
Date: Fri, 29 Jan 2016 21:46:01 GMT
Content-Length: 26
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
+ Body
```
Argument 'key' is required
```
+ Request With Empty Argument
The response is the same if the argument is invalid. For instance:
curl -i "http://localhost:5001/api/v0/block/get?arg=kitten"
#### curl
curl -i "http://localhost:5001/api/v0/block/get?arg="
+ Body
```
curl -i "http://localhost:5001/api/v0/block/get?arg="
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 17:49:54 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "Not a valid hash"
- Code: 0
+ Body
```
{
"Message": "Not a valid hash",
"Code": 0
}
```
+ Request With Valid Argument
#### curl
curl -i "http://localhost:5001/api/v0/block/get?arg=QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o"
+ Body
```
curl -i "http://localhost:5001/api/v0/block/get?arg=QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: text/plain
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
X-Stream-Output: 1
Date: Thu, 28 Apr 2016 17:50:04 GMT
Transfer-Encoding: chunked
```
+ Attributes (string)
+ Body
```
hello world
```
## put [POST /block/put{?arg}]
Stores input as an IPFS block
'ipfs block put' is a plumbing command for storing raw IPFS blocks.
+ Parameters
+ arg (string, required) - The data to be stored as an IPFS block.
+ Request Without Arguments
#### curl
curl -i -X POST "http://localhost:5001/api/v0/block/put"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/block/put"
```
+ Response 400
+ Headers
```
Date: Fri, 29 Jan 2016 21:48:34 GMT
Content-Length: 32
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
+ Body
```
File argument 'data' is required
```
+ Request Invalid Argument (multipart/form-data)
The response is the same if there is no data provided. For example:
curl -i -X POST -F "data=" "http://localhost:5001/api/v0/block/put"
#### curl
curl -i -X POST -F "data=invalid" "http://localhost:5001/api/v0/block/put"
+ Body
```
curl -i -X POST -F "data=invalid" "http://localhost:5001/api/v0/block/put"
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 17:50:15 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "mime: no media type"
- Code: 0
+ Body
```
{
"Message": "mime: no media type",
"Code": 0
}
```
+ Request Valid Argument (multipart/form-data)
In the example provided, the 'test' file has the following contents:
```
hello world
```
#### curl
curl -i -X POST -F "data=@test" "http://localhost:5001/api/v0/block/put"
+ Body
```
curl -i -X POST -F "data=@test" "http://localhost:5001/api/v0/block/put"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:49:22 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
- Key: "QmZjTnYw2TFhn9Nn7tjmPSoTBoY7YRkwPzwSrSbabY24Kp" (Multihash)
- Size: 12 (number)
+ Body
```
{
"Key": "QmZjTnYw2TFhn9Nn7tjmPSoTBoY7YRkwPzwSrSbabY24Kp",
"Size": 12
}
```
## stat [GET /block/stat{?arg}]
Retrieve information on a raw ipfs block.
+ Parameters
+ arg (Multihash, required) - The base58 multihash of an existing block to get.
+ Request Without Arguments
#### curl
curl -i "http://localhost:5001/api/v0/block/stat"
+ Body
```
curl -i "http://localhost:5001/api/v0/block/stat"
```
+ Response 400
+ Headers
```
Date: Fri, 29 Jan 2016 21:25:34 GMT
Content-Length: 26
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
+ Body
```
Argument 'key' is required
```
+ Request Invalid Argument
The response is the same if there is no argument provided. For example:
curl -i -F "data=" "http://localhost:5001/api/v0/block/stat/arg="
#### curl
curl -i "http://localhost:5001/api/v0/block/stat/arg=kitten"
+ Body
```
curl -i "http://localhost:5001/api/v0/block/stat/arg=kitten"
```
+ Response 400
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:49:33 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "Not a valid hash"
- Code: 0
+ Body
```
{
"Message": "Not a valid hash",
"Code": 0
}
```
+ Request Valid Argument
#### curl
curl -i "http://localhost:5001/api/v0/block/stat?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ"
+ Body
```
curl -i "http://localhost:5001/api/v0/block/stat?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:49:43 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
+ Key (Multihash)
+ Size (number) - the size of the block in bytes
+ Body
```
{
"Key": "QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ",
"Size": 55
}
```
# Group bootstrap
Show or edit the list of bootstrap peers.
Requesting `ipfs/bootstrap` with no arguments will return `ipfs/bootstrap/list`.
**Security Warning**:
The bootstrap command manipulates the `bootstrap list`, which contains
the addresses of bootstrap nodes. These are the *trusted peers* from
which to learn about other peers in the network. Only edit this list
if you understand the risks of adding or removing nodes from this list.
+ Request No Subcommands
#### curl
curl -i http://localhost:5001/api/v0/bootstrap
+ Body
```
curl -i http://localhost:5001/api/v0/bootstrap
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output
Content-Type: application/json
Trailer: X-Stream-Error
Transfer-Encoding: chunked
Date: Fri, 29 Jan 2016 22:29:38 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
+ Peers (array)
- (MultiAddr)
+ Body
```
{
"Peers": [
"/ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ",
"/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z",
"/ip4/104.236.179.241/tcp/4001/ipfs/QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM",
"/ip4/162.243.248.213/tcp/4001/ipfs/QmSoLueR4xBeUbY9WZ9xGUUxunbKWcrNFTDAadQJmocnWm",
"/ip4/128.199.219.111/tcp/4001/ipfs/QmSoLSafTMBsPKadTEgaXctDQVcqN88CNLHXMkTNwMKPnu",
"/ip4/104.236.76.40/tcp/4001/ipfs/QmSoLV4Bbm51jM9C4gDYZQ9Cy3U6aXMJDAbzgu2fzaDs64",
"/ip4/178.62.158.247/tcp/4001/ipfs/QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd",
"/ip4/178.62.61.185/tcp/4001/ipfs/QmSoLMeWqB7YGVLJN3pNLQpmmEk35v6wYtsMGLzSr5QBU3",
"/ip4/104.236.151.122/tcp/4001/ipfs/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx"
]
}
```
## add [GET /bootstrap/add{?arg}{&default}]
Add peers to the bootstrap list.
Outputs a list of peers that were added (that weren't already
in the bootstrap list).
+ Parameters
+ arg (MultiAddr, required) - A peer to add to the bootstrap list.
+ default (boolean, optional) - Add default bootstrap nodes. Default: false.
+ Request No Arguments
#### curl
curl -i http://localhost:5001/api/v0/bootstrap/add
+ Body
```
curl -i http://localhost:5001/api/v0/bootstrap/add
```
+ Response 400
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:49:55 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "no bootstrap peers to add"
- Code: 1
+ Body
```
{
"Message": "no bootstrap peers to add",
"Code": 1
}
```
+ Request Invalid Argument
#### curl
curl -i http://localhost:5001/api/v0/bootstrap/add?arg=QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ
+ Body
```
curl -i http://localhost:5001/api/v0/bootstrap/add?arg=QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:50:05 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "invalid multiaddr, must begin with /"
- Code: 0
+ Body
```
{
"Message": "invalid multiaddr, must begin with /",
"Code": 0
}
```
+ Request Empty Argument
#### curl
curl -i http://localhost:5001/api/v0/bootstrap/add?arg=
+ Body
```
curl -i http://localhost:5001/api/v0/bootstrap/add?arg=
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:50:24 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "invalid ipfs address"
- Code: 0
+ Body
```
{
"Message": "invalid ipfs address",
"Code": 0
}
```
+ Request Valid Argument
#### curl
curl -i http://localhost:5001/api/v0/bootstrap/add?arg=/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z
+ Body
```
curl -i http://localhost:5001/api/v0/bootstrap/add?arg=/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:50:47 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
+ Peers (array)
- (MultiAddr)
+ Body
```
{
"Peers": [
"/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z"
]
}
```
+ Request Default Option
#### curl
curl -i http://localhost:5001/api/v0/bootstrap/add?default
+ Body
```
curl -i http://localhost:5001/api/v0/bootstrap/add?default
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:51:05 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
+ Peers (array)
- (MultiAddr)
+ Body
```
{
"Peers": [
"/ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ",
"/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z",
"/ip4/104.236.179.241/tcp/4001/ipfs/QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM",
"/ip4/162.243.248.213/tcp/4001/ipfs/QmSoLueR4xBeUbY9WZ9xGUUxunbKWcrNFTDAadQJmocnWm",
"/ip4/128.199.219.111/tcp/4001/ipfs/QmSoLSafTMBsPKadTEgaXctDQVcqN88CNLHXMkTNwMKPnu",
"/ip4/104.236.76.40/tcp/4001/ipfs/QmSoLV4Bbm51jM9C4gDYZQ9Cy3U6aXMJDAbzgu2fzaDs64",
"/ip4/178.62.158.247/tcp/4001/ipfs/QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd",
"/ip4/178.62.61.185/tcp/4001/ipfs/QmSoLMeWqB7YGVLJN3pNLQpmmEk35v6wYtsMGLzSr5QBU3",
"/ip4/104.236.151.122/tcp/4001/ipfs/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx"
]
}
```
## list [GET /bootstrap/list]
Show peers in the bootstrap list
+ Request Without Options
#### curl
curl -i http://localhost:5001/api/v0/bootstrap/list
+ Body
```
curl -i http://localhost:5001/api/v0/bootstrap/list
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:51:19 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
+ Peers (array)
- (MultiAddr)
+ Body
```
{
"Peers": [
"/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z",
"/ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ",
"/ip4/104.236.179.241/tcp/4001/ipfs/QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM",
"/ip4/162.243.248.213/tcp/4001/ipfs/QmSoLueR4xBeUbY9WZ9xGUUxunbKWcrNFTDAadQJmocnWm",
"/ip4/128.199.219.111/tcp/4001/ipfs/QmSoLSafTMBsPKadTEgaXctDQVcqN88CNLHXMkTNwMKPnu",
"/ip4/104.236.76.40/tcp/4001/ipfs/QmSoLV4Bbm51jM9C4gDYZQ9Cy3U6aXMJDAbzgu2fzaDs64",
"/ip4/178.62.158.247/tcp/4001/ipfs/QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd",
"/ip4/178.62.61.185/tcp/4001/ipfs/QmSoLMeWqB7YGVLJN3pNLQpmmEk35v6wYtsMGLzSr5QBU3",
"/ip4/104.236.151.122/tcp/4001/ipfs/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx"
]
}
```
## rm [GET /bootstrap/rm{?arg}{&all}]
Removes peers from the bootstrap list.
Outputs the list of peers that were removed.
+ Parameters
+ arg (MultiAddr, optional) - A peer to add to the bootstrap list
+ all (boolean, optional) - Remove all bootstrap peers. Default: false.
+ Request Without Options
#### curl
curl -i http://localhost:5001/api/v0/bootstrap/rm
+ Body
```
curl -i http://localhost:5001/api/v0/bootstrap/rm
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:51:30 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
+ Peers: [] (array)
+ Body
```
{
"Peers": []
}
```
+ Request With All
#### curl
curl -i http://localhost:5001/api/v0/bootstrap/rm?all
+ Body
```
curl -i http://localhost:5001/api/v0/bootstrap/rm?all
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:51:45 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
+ Peers (array)
- (MultiAddr)
+ Body
```
{
"Peers": [
"/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z",
"/ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ",
"/ip4/104.236.179.241/tcp/4001/ipfs/QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM",
"/ip4/162.243.248.213/tcp/4001/ipfs/QmSoLueR4xBeUbY9WZ9xGUUxunbKWcrNFTDAadQJmocnWm",
"/ip4/128.199.219.111/tcp/4001/ipfs/QmSoLSafTMBsPKadTEgaXctDQVcqN88CNLHXMkTNwMKPnu",
"/ip4/104.236.76.40/tcp/4001/ipfs/QmSoLV4Bbm51jM9C4gDYZQ9Cy3U6aXMJDAbzgu2fzaDs64",
"/ip4/178.62.158.247/tcp/4001/ipfs/QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd",
"/ip4/178.62.61.185/tcp/4001/ipfs/QmSoLMeWqB7YGVLJN3pNLQpmmEk35v6wYtsMGLzSr5QBU3",
"/ip4/104.236.151.122/tcp/4001/ipfs/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx"
]
}
```
+ Request With Empty Argument
#### curl
curl -i http://localhost:5001/api/v0/bootstrap/rm?arg=
+ Body
```
curl -i http://localhost:5001/api/v0/bootstrap/rm?arg=
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:52:02 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "invalid ipfs address"
- Code: 0
+ Body
```
{
"Message": "invalid ipfs address",
"Code": 0
}
```
+ Request With Invalid Argument
#### curl
curl -i http://localhost:5001/api/v0/bootstrap/rm?arg=invalid
+ Body
```
curl -i http://localhost:5001/api/v0/bootstrap/rm?arg=invalid
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:52:14 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "invalid multiaddr, must begin with /"
- Code: 0
+ Body
```
{
"Message": "invalid multiaddr, must begin with /",
"Code": 0
}
```
+ Request With Valid Argument
#### curl
curl -i http://localhost:5001/api/v0/bootstrap/rm?arg=/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z
+ Body
```
curl -i http://localhost:5001/api/v0/bootstrap/rm?arg=/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:52:23 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
+ Peers (array)
- (Multihash)
+ Body
```
{
"Peers": []
}
```
# Group cat
Show IPFS object data.
## cat [GET /cat{?arg}]
Displays the data contained by an IPFS or IPNS object(s) at the given path.
+ Parameters
+ arg (string, required) - The path to the IPFS object or objects to be outputted.
+ Request Without Arguments
#### curl
curl -i "http://localhost:5001/api/v0/cat"
+ Body
```
curl -i "http://localhost:5001/api/v0/cat"
```
+ Response 400
+ Headers
```
Date: Fri, 05 Feb 2016 17:14:24 GMT
Content-Length: 32
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
This is the raw content of the file.
+ Body
```
Argument 'ipfs-path' is required
```
+ Request With Empty Argument
The response is the same if there is an invalid argument. For example:
curl -i "http://localhost:5001/api/v0/cat?arg=kitten"
#### curl
curl -i "http://localhost:5001/api/v0/cat?arg="
+ Body
```
curl -i "http://localhost:5001/api/v0/cat?arg="
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 15:54:57 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "invalid ipfs ref path"
- Code: 0
+ Body
```
{
"Message": "invalid ipfs ref path",
"Code": 0
}
```
+ Request With Valid Argument But Invalid DAG Node
The multihash in this request is for a directory, not for an object.
#### curl
curl -i "http://localhost:5001/api/v0/cat?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ"
+ Body
```
curl -i "http://localhost:5001/api/v0/cat?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ"
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 15:55:11 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "this dag node is a directory"
- Code: 0
+ Body
```
{
"Message": "this dag node is a directory",
"Code": 0
}
```
+ Request With Valid Argument
In this request, 'QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o' is the hash for a file, 'test',
with the following contents
```
hello world
```
#### curl
curl -i "http://localhost:5001/api/v0/cat?arg=QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o"
+ Body
```
curl -i "http://localhost:5001/api/v0/cat?arg=QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o"
```
+ Response 200
The Content-Type of the response should be `application/x-tar`.
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: text/plain
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
X-Content-Length: 12
X-Stream-Output: 1
Date: Thu, 28 Apr 2016 15:55:24 GMT
Transfer-Encoding: chunked
```
+ Attributes (string)
+ Body
```
hello world
```
# Group commands
Lists all available commands.
## commands [GET /commands]
Lists all available commands (and subcommands) and exits.
+ Request
#### curl
curl -i http://localhost:5001/api/v0/commands
+ Body
```
curl -i http://localhost:5001/api/v0/commands
```
+ Response 200
Due to the size of the response, no Body is included here, and only one level depth for the Attributes.
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:56:11 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
- Name: "ipfs" (string)
+ Subcommands (array)
- Name (string)
+ Subcommands (object)
+ Options (array)
- ShowOptions: false (boolean)
+ Options (array)
- "{}" (object)
- ShowOptions: false (boolean)
# Group config
## config [POST /config{?arg1,arg2}{&bool,json}]
'ipfs config' controls configuration variables. It works
much like 'git config'. The configuration values are stored in a config
file inside your IPFS repository.
+ Parameters
+ arg1: "Datastore.Path" (string, required) - The key of the config entry.
+ arg2: "~/.ipfs/datastore" (string, optional) - The value to set the config entry to.
+ bool (boolean, optional) - Set a boolean. Default: false.
+ json (boolean, optional) - Parse stringified JSON. Default: false.
+ Request Without Arguments
#### curl
curl -i -X POST "http://localhost:5001/api/v0/config"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/config"
```
+ Response 400
+ Headers
```
Date: Tue, 02 Feb 2016 16:37:00 GMT
Content-Length: 26
Content-Type: text/plain; charset=utf-8
```
+ Body
```
Argument 'key' is required
```
+ Request With Invalid Argument
#### curl
curl -i -X POST "http://localhost:5001/api/v0/config?arg=kitten"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/config?arg=kitten"
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:56:23 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
+ Message: "Failed to get config value: key has no attributes"
+ Code: 0
+ Body
```
{
"Message": "Failed to get config value: key has no attributes",
"Code": 0
}
```
+ Request With Argument
#### curl
curl -i -X POST "http://localhost:5001/api/v0/config?arg=API.HTTPHeaders"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/config?arg=API.HTTPHeaders"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:56:32 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
+ `Key`: "Datastore" (string)
+ `Value` (object, nullable) - The config entry.
+ Body
```
{
"Key": "API.HTTPHeaders",
"Value": null
}
```
+ Request As Subcommand
#### curl
curl -i -X POST "http://localhost:5001/api/v0/config/API.HTTPHeaders"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/config/API.HTTPHeaders"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:56:42 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
+ `Key`: "Datastore" (string)
+ `Value` (object, nullable) - The config entry.
+ Body
```
{
"Key": "API.HTTPHeaders",
"Value": null
}
```
+ Request With Both Args
#### curl
curl -i -X POST "http://localhost:5001/api/v0/config?arg=Datastore.Path&arg=kitten"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/config?arg=Datastore.Path&arg=kitten"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:56:57 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
- Key: "Datastore.Path" (string)
- Value: "kitten" (string)
+ Body
```
{
"Key": "Datastore.Path",
"Value": "kitten"
}
```
+ Request With Both Args and JSON Flag With Invalid JSON Argument
#### curl
curl -i -X POST "http://localhost:5001/api/v0/config?arg=Datastore.Path&arg=kitten&json"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/config?arg=Datastore.Path&arg=kitten&json"
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:57:08 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "failed to unmarshal json. invalid character 'k' looking for beginning of value"
- Code: 0
+ Body
```
{
"Message": "failed to unmarshal json. invalid character 'k' looking for beginning of value",
"Code": 0
}
```
+ Request With Both Args and JSON Flag With Valid JSON Argument
#### curl
curl -i -X POST "http://localhost:5001/api/v0/config?arg=Datastore.Path&arg=\"kitten\"&json"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/config?arg=Datastore.Path&arg=\"kitten\"&json"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:57:20 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
- Key: "Datastore.Path" (string)
- Value: "kitten" (string)
+ Body
```
{
"Key": "Datastore.Path",
"Value": "kitten"
}
```
## replace [POST /config/replace{?arg}]
Replaces the config with <file>.
Make sure to back up the config file first if neccessary, as this operation
can't be undone.
#### curl
curl -i -X POST -F "file=@test" "http://localhost:5001/api/v0/config/replace"
+ Parameters
+ arg (string, required) - The file to use as the new config.
+ Request Without File
#### curl
curl -i -X POST "http://localhost:5001/api/v0/config/replace"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/config/replace"
```
+ Response 400
+ Headers
```
Date: Tue, 02 Feb 2016 22:31:15 GMT
Content-Length: 32
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
+ Body
```
File argument 'file' is required
```
+ Request With Badly Configured Config File
Where 'test' is a file that is not JSON and does not conform to the
standard IPFS config file structure.
#### curl
curl -i -X POST -F "file=@test" http://localhost:5001/api/v0/config/replace
+ Body
```
curl -i -X POST -F "file=@test" http://localhost:5001/api/v0/config/replace
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:57:31 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "Failed to decode file as config" (string)
- Code: 0 (number)
+ Body
```
{
"Message": "Failed to decode file as config",
"Code": 0
}
```
+ Request With Config File
#### curl
curl -i -X POST -F "file=@test" http://localhost:5001/api/v0/config/replace
+ Body
```
curl -i -X POST -F "file=@test" http://localhost:5001/api/v0/config/replace
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 16:58:13 GMT
Transfer-Encoding: chunked
```
+ Attributes
+ Body
```
```
## show [GET /config/show]
Outputs the content of the config file
**Warning**
Your private key is stored in the config file, and it will be
included in the output of this command.
+ Request Without Config File
This request is shown as an example, presuming that ~/.ipfs/config has been
deleted, not that it hasn't been specified in the request.
#### curl
curl -i "http://localhost:5001/api/v0/config/show"
+ Body
```
curl -i http://localhost:5001/api/v0/config/show
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: text/plain
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
X-Stream-Output: 1
Date: Thu, 28 Apr 2016 16:58:24 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "open /Users/richard/.ipfs/config: no such file or directory" (string)
- Code: 0 (number)
+ Body
```
{
"Message": "open /Users/richard/.ipfs/config: no such file or directory",
"Code": 0
}
```
+ Request
#### curl
curl -i "http://localhost:5001/api/v0/config/show"
+ Body
```
curl -i "http://localhost:5001/api/v0/config/show"
```
+ Response 200
A Body is not included here in order to obfuscate the private key.
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: text/plain
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
X-Stream-Output: 1
Date: Thu, 28 Apr 2016 16:58:39 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
+ `API` (object)
+ `HTTPHeaders` (string, nullable)
+ `Addresses` (object)
+ `API`: "/ip4/127.0.0.1/tcp/5001" (MultiAddr)
+ `Gateway`: "/ip4/127.0.0.1/tcp/8080" (MultiAddr)
+ `Swarm` (array)
- (SwarmAddrs)
+ `Bootstrap` (array)
- MultiAddr (MultiAddr)
+ `Datastore` (object)
- `GCPeriod`: "" (string)
- `NoSync`: false (boolean)
- `Params` (string, nullable)
- `Path`: "" (string)
- `StorageGCWatermark`: 90 (number)
- `StorageMax`: "10GB" (string)
- `Type`: "" (string)
+ `Discovery` (object)
+ `MDNS` (object)
- `Enabled`: true (boolean)
- `Interval`: 10 (number)
+ `Gateway` (object)
- `HTTPHeaders` (string, nullable)
- `RootRedirect`: "" (string)
- `Writable`: false (boolean)
+ `Identity` (object)
- `PeerID`: hash (Multihash)
- `PrivKey`: hash (string)
+ `Ipns` (object)
- `RecordLifetime`: "" (string)
- `RepublishPeriod`: "" (string)
- `ResolveCacheSize`: 128 (number)
+ `Log` (object)
- `MaxAgeDays`: 0 (number)
- `MaxBackups`: 1 (number)
- `MaxSizeMB`: 250 (number)
+ `Mounts` (object)
- `FuseAllowOther`: false (boolean)
- `IPFS`: "/ipfs" (string)
- `IPFS`: "/ipns" (string)
+ `SupernodeRouting` (object)
+ `Servers` (array)
- (SwarmAddrs)
+ `Swarm` (object)
- `AddrFilters` (string, nullable)
+ `Tour` (object)
- `Last`: "" (string)
+ `Version` (object)
- `AutoUpdate`: "minor" (string)
- `Check`: "error" (string)
- `CheckDate`: "0001-01-01T00:00:00Z" (string)
- `CheckPeriod`: "172800000000000" (string)
- `Current`: "0.4.0-dev" (string)
+ `id` (Multihash)
# Group dht
Issue commands directly through the DHT.
This command can't be called directly.
## findpeer [GET /dht/findpeer{?arg}]
Query the DHT for all of the multiaddresses associated with a Peer ID.
+ Parameters
+ arg (string, required) - The ID of the peer to search for.
+ Request Without Arguments
#### curl
curl -i "http://localhost:5001/api/v0/dht/findpeer"
+ Body
```
curl -i "http://localhost:5001/api/v0/dht/findpeer"
```
+ Response 400
+ Headers
```
Date: Wed, 13 Apr 2016 14:08:32 GMT
Content-Length: 29
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
+ Body
```
Argument 'peerID' is required
```
+ Request With Empty Argument
#### curl
curl -i "http://localhost:5001/api/v0/dht/findpeer?arg="
+ Body
```
curl -i "http://localhost:5001/api/v0/dht/findpeer?arg="
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Wed, 13 Apr 2016 14:08:49 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "multihash too short. must be \u003e 3 bytes"
- Code: 0
+ Body
```
{
"Message": "multihash too short. must be \u003e 3 bytes",
"Code": 0
}
```
+ Request With Invalid Argument
#### curl
curl -i "http://localhost:5001/api/v0/dht/findpeer?arg=kitten"
+ Body
```
curl -i "http://localhost:5001/api/v0/dht/findpeer?arg=kitten"
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Wed, 13 Apr 2016 14:09:05 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "multihash length inconsistent: \u0026{6 174 [128 54 35]}"
- Code: 0
+ Body
```
{
"Message": "multihash length inconsistent: \u0026{6 174 [128 54 35]}",
"Code": 0
}
```
+ Request With Argument
#### curl
curl -i "http://localhost:5001/api/v0/dht/findpeer?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ"
+ Body
```
curl -i "http://localhost:5001/api/v0/dht/findpeer?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ"
```
+ Response 200
The response has been truncated to a single ndjson object, as the responses are streamed.
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
X-Chunked-Output: 1
Date: Wed, 13 Apr 2016 14:09:20 GMT
Transfer-Encoding: chunked
```
+ Attributes (ndjson)
- Extra (string)
- ID (Multihash)
+ Responses (array)
+ (object)
- Addrs (MultiAddr)
- ID (Multihash)
- Type (number)
+ Body
```
{
"Extra": "",
"ID": "QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd",
"Responses": [
{
"Addrs": [
"/ip4/10.0.0.116/tcp/14001",
"/ip4/127.0.0.1/tcp/14001",
"/ip4/127.0.0.2/tcp/14001",
"/ip4/62.210.92.54/tcp/14001"
],
"ID": "QmdmznJmndCNmfDNZ6pLSFuihXwgSnHbienWCJzJQ4M8By"
},
...
],
"Type": 0
}
```
## findprovs [POST /dht/findprovs{?arg}]
Find peers in the DHT that can provide a specific value, given a key.
+ Parameters
+ arg (string, required) - The key to find providers for.
+ Request Without Arguments
#### curl
curl -i -X POST "http://localhost:5001/api/v0/dht/findprovs"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/dht/findprovs"
```
+ Response 400
+ Headers
```
Date: Sat, 06 Feb 2016 22:50:36 GMT
Content-Length: 26
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
+ Body
```
Argument 'key' is required
```
+ Request With Argument
The response is the same if the argument is empty or invalid. For example:
curl -i -X POST "http://localhost:5001/api/v0/dht/findprovs?arg=kitten"
#### curl
curl -i -X POST "http://localhost:5001/api/v0/dht/findprovs?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/dht/findprovs?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ"
```
+ Response 200
The response has been truncated to a single ndjson object, as the responses are streamed.
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
X-Chunked-Output: 1
Date: Wed, 13 Apr 2016 14:10:51 GMT
Transfer-Encoding: chunked
```
+ Attributes (ndjson)
- Extra (string)
- ID (Multihash)
+ Responses (array)
+ (object)
- Addrs (MultiAddr)
- ID (Multihash)
- Type (number)
+ Body
```
{
"Extra": "",
"ID": "QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd",
"Responses": [
{
"Addrs": [
"/ip4/10.0.0.116/tcp/14001",
"/ip4/127.0.0.1/tcp/14001",
"/ip4/127.0.0.2/tcp/14001",
"/ip4/62.210.92.54/tcp/14001"
],
"ID": "QmdmznJmndCNmfDNZ6pLSFuihXwgSnHbienWCJzJQ4M8By"
},
...
],
"Type": 0
}
```
## get [GET /dht/get{?arg}]
Given a key, query the DHT for its best value.
There may be several different values for a given key stored in the DHT; in this context 'best' means the record that is most desirable. There is no one metric for 'best': it depends entirely on the key type. For IPNS, 'best' is the record that is both valid and has the highest sequence number (freshest). Different key types can specify other 'best' rules.
+ Parameters
+ arg (string, required) - The key to find providers for
+ Request Without Arguments
#### curl
curl -i "http://localhost:5001/api/v0/dht/get"
+ Body
```
curl -i "http://localhost:5001/api/v0/dht/get"
```
+ Response 400
+ Headers
```
Date: Sat, 06 Feb 2016 22:59:08 GMT
Content-Length: 26
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
+ Body
```
Argument 'key' is required
```
+ Request With Argument
The response is the same if the argument is empty or invalid. For example:
curl -i "http://localhost:5001/api/v0/dht/get?arg=\[kitten\]"
#### curl
curl -i "http://localhost:5001/api/v0/dht/get?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ"
+ Body
```
curl -i "http://localhost:5001/api/v0/dht/get?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ"
```
+ Response 200
The response has been truncated to a single ndjson object, as the responses are streamed.
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
X-Chunked-Output: 1
Date: Thu, 28 Apr 2016 16:59:34 GMT
Transfer-Encoding: chunked
```
+ Attributes (ndjson)
- Extra (string)
- ID (Multihash)
+ Responses (array)
+ (object)
- Addrs (MultiAddr)
- ID (Multihash)
- Type (number)
+ Body
```
{
"Extra": "",
"ID": "QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd",
"Responses": [
{
"Addrs": [
"/ip4/10.0.0.116/tcp/14001",
"/ip4/127.0.0.1/tcp/14001",
"/ip4/127.0.0.2/tcp/14001",
"/ip4/62.210.92.54/tcp/14001"
],
"ID": "QmdmznJmndCNmfDNZ6pLSFuihXwgSnHbienWCJzJQ4M8By"
},
...
],
"Type": 0
}
```
## put [GET /dht/put{?arg1,arg2}]
Write a key/value pair to the DHT.
Given a key of the form /foo/bar and a value of any form, this will write that value to the DHT with that key.
Keys have two parts: a keytype (foo) and the key name (bar). IPNS uses the /ipns keytype, and expects the key name to be a Peer ID. IPNS entries are specifically formatted (protocol buffer).
You may only use keytypes that are supported in your ipfs binary: currently this is only /ipns. Unless you have a relatively deep understanding of the go-ipfs DHT internals, you likely want to be using 'ipfs name publish' instead of this.
Value is arbitrary text. Standard input can be used to provide value.
NOTE: A value may not exceed 2048 bytes.
+ Parameters
+ arg1 (string, required) - The key to store the value at.
+ arg2 (string, required) - The value to store.
+ Request Without Arguments
#### curl
curl -i "http://localhost:5001/api/v0/dht/put"
+ Body
```
curl -i "http://localhost:5001/api/v0/dht/put"
```
+ Response 400
+ Headers
```
Date: Sat, 06 Feb 2016 23:01:30 GMT
Content-Length: 26
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
+ Body
```
Argument 'key' is required
```
+ Request With Empty Or Invalid First Argument
#### curl
curl -i "http://localhost:5001/api/v0/dht/put?arg="
+ Body
```
curl -i "http://localhost:5001/api/v0/dht/put?arg="
```
+ Response 400
+ Headers
```
Date: Sat, 06 Feb 2016 23:02:04 GMT
Content-Length: 28
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
+ Body
```
Argument 'value' is required
```
+ Request With Arguments
The response has been truncated to a single ndjson object, as the responses are streamed.
The response is the same if either argument is empty or invalid. For example:
curl -i "http://localhost:5001/api/v0/dht/put?arg=&arg="
#### curl
curl -i "http://localhost:5001/api/v0/dht/put?arg=kitten&arg=true"
+ Body
```
curl -i "http://localhost:5001/api/v0/dht/put?arg=kitten&arg=true"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
X-Chunked-Output: 1
Date: Thu, 28 Apr 2016 17:00:12 GMT
Transfer-Encoding: chunked
```
+ Attributes (ndjson)
- Extra (string)
- ID (Multihash)
+ Responses (array)
+ (object)
- Addrs (MultiAddr)
- ID (Multihash)
- Type (number)
+ Body
```
{
"Extra": "",
"ID": "QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd",
"Responses": [
{
"Addrs": [
"/ip4/10.0.0.116/tcp/14001",
"/ip4/127.0.0.1/tcp/14001",
"/ip4/127.0.0.2/tcp/14001",
"/ip4/62.210.92.54/tcp/14001"
],
"ID": "QmdmznJmndCNmfDNZ6pLSFuihXwgSnHbienWCJzJQ4M8By"
},
...
],
"Type": 0
}
```
## query [GET /dht/query{?arg}]
Find the closest Peer IDs to a given Peer ID by querying the DHT
+ Parameters
+ arg (string, required) - The peerID to run the query against.
+ Request Without Arguments
#### curl
curl -i "http://localhost:5001/api/v0/dht/query"
+ Body
```
curl -i "http://localhost:5001/api/v0/dht/query"
```
+ Response 400
+ Headers
```
Date: Sat, 06 Feb 2016 23:04:52 GMT
Content-Length: 29
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
+ Body
```
Argument 'peerID' is required
```
+ Request With Argument
#### curl
curl -i "http://localhost:5001/api/v0/dht/query?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ"
+ Body
```
curl -i "http://localhost:5001/api/v0/dht/query?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
X-Chunked-Output: 1
Date: Wed, 13 Apr 2016 14:24:22 GMT
Transfer-Encoding: chunked
```
+ Attributes (ndjson)
- Extra (string)
- ID (Multihash)
+ Responses (array)
+ (object)
- Addrs (MultiAddr)
- ID (Multihash)
- Type (number)
+ Body
```
{
"Extra": "",
"ID": "QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd",
"Responses": [
{
"Addrs": [
"/ip4/10.0.0.116/tcp/14001",
"/ip4/127.0.0.1/tcp/14001",
"/ip4/127.0.0.2/tcp/14001",
"/ip4/62.210.92.54/tcp/14001"
],
"ID": "QmdmznJmndCNmfDNZ6pLSFuihXwgSnHbienWCJzJQ4M8By"
},
...
],
"Type": 0
}
```
# Group diag
Generate diagnostic reports.
This command can't be called directly.
## cmds [GET /diag/cmds]
List commands run on this ipfs node.
+ Request
#### curl
curl -i "http://localhost:5001/api/v0/diag/cmds"
+ Body
```
curl -i "http://localhost:5001/api/v0/diag/cmds"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Tue, 26 Apr 2016 23:21:50 GMT
Transfer-Encoding: chunked
```
+ Attributes (array)
+ (object)
- Active (boolean)
+ Args (array, nullable)
- Command (string)
- EndTime (string)
- ID (number)
+ Options (object)
- enc (string)
+ StartTime (string)
+ Body
```
[
{
"Active": true,
"Args": [],
"Command": "diag/cmds",
"EndTime": "0001-01-01T00:00:00Z",
"ID": 19,
"Options": {
"enc": "json"
},
"StartTime": "2016-04-26T19:22:41.376294115-04:00"
}
]
```
## cmds clear [GET /diag/cmds/clear]
Clear inactive requests from the log.
+ Request
#### curl
curl -i "http://localhost:5001/api/v0/diag/cmds/clear"
+ Body
```
curl -i "http://localhost:5001/api/v0/diag/cmds/clear"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 14:26:49 GMT
Transfer-Encoding: chunked
```
+ Attributes (string)
+ Body
```
```
## cmds set-time [GET /diag/cmds/set-time{?arg}]
Set how long to keep inactive requests in the log.
+ Parameters
+ arg (string, required) - Time to keep inactive requests in log. // TODO Switch to Time on rebase
+ Request Without Argument
#### curl
curl -i "http://localhost:5001/api/v0/diag/cmds/set-time"
+ Body
```
curl -i "http://localhost:5001/api/v0/diag/cmds/set-time"
```
+ Response 400
+ Headers
```
Date: Fri, 18 Mar 2016 21:28:38 GMT
Content-Length: 27
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
+ Body
```
Argument 'time' is required
```
+ Request With Empty Argument
The repsonse is the same if the argument is invalid. For example:
curl -i "http://localhost:5001/api/v0/diag/cmds/set-time?arg=kitten"
#### curl
curl -i "http://localhost:5001/api/v0/diag/cmds/set-time"
+ Body
```
curl -i "http://localhost:5001/api/v0/diag/cmds/set-time"
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 14:39:43 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "time: invalid duration "
- Code: 0
+ Body
```
{
"Code": 0,
"Message": "time: invalid duration "
}
```
+ Request With Valid Argument
#### curl
curl -i "http://localhost:5001/api/v0/diag/cmds/set-time?arg=1s"
+ Body
```
curl -i "http://localhost:5001/api/v0/diag/cmds/set-time?arg=1s"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 14:39:59 GMT
Transfer-Encoding: chunked
```
+ Attributes (string)
+ Body
```
```
## net [GET /diag/net{?vis}]
Sends out a message to each node in the network recursively
requesting a listing of data about them including number of
connected peers and latencies between them.
The given timeout will be decremented 2s at every network hop,
ensuring peers try to return their diagnostics before the initiator's
timeout. If the timeout is too small, some peers may not be reached.
30s and 60s are reasonable timeout values, though networks vary.
The default timeout is 20 seconds.
+ Parameters
+ vis (enum[string], optional) - Output format.
- Default: `text`
+ Members
- `text` - Easy to read.
- `d3` - JSON ready to be fed into d3view.
- `dot` - Graphviz format.
+ Request Without Arguments
#### curl
curl -i "http://localhost:5001/api/v0/diag/net"
+ Body
```
curl -i "http://localhost:5001/api/v0/diag/net"
```
+ Response 200
The response Body is exceedingly large: here, it has been sampled.
The format is `plain text`.
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: text/plain
Server: go-ipfs/0.4.0-dev
Trailer: X-Stream-Error
X-Stream-Output: 1
Date: Fri, 18 Mar 2016 21:39:47 GMT
Transfer-Encoding: chunked
```
+ Attributes (string)
+ Body
```
ID Qmece2RkXhsKe5CRooNisBTh4SK119KrXXGmoK6V3kb8aH up 184 seconds connected to 10:
ID QmSdFMkJGoG1VRxUfrKGivxUvnfefUsGPrAVtAug8CJRm6 connections: 1 latency: 243965153 ns
ID QmZzPcDwgaoqhvfE1QW91J8SG9G2M8wGJaaPmNDKRGw1LN connections: 1 latency: 371879189 ns
ID QmSoLPppuBtQSGwKDZT2M73ULpjvfd3aZ6ha4oFGL1KrGM connections: 1 latency: 607917705 ns
ID QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ connections: 1 latency: 293064495 ns
ID QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z connections: 1 latency: 1159858705 ns
ID QmTv99LaBwegvtRgUaUUy6JSzF6q8i2FCJdy7fJQxqAtU8 connections: 1 latency: 244056752 ns
ID QmSoLueR4xBeUbY9WZ9xGUUxunbKWcrNFTDAadQJmocnWm connections: 1 latency: 164713121 ns
ID QmT19P4HExyfDqZAU65LWyuuJU31G8uWKPoFkQPEcqYGD2 connections: 1 latency: 298962573 ns
ID QmVjEQAUXCEQMDmvgtsd5f2EsgTbg33Cpis5TDM3uVP9Vs connections: 1 latency: 349706701 ns
ID QmSoLSafTMBsPKadTEgaXctDQVcqN88CNLHXMkTNwMKPnu connections: 1 latency: 3586431786 ns
ID QmSoLueR4xBeUbY9WZ9xGUUxunbKWcrNFTDAadQJmocnWm up 18824 seconds connected to 68:
...
```
+ Request With Vis Option d3
#### curl
curl -i "http://localhost:5001/api/v0/diag/net?vis=d3"
+ Body
```
curl -i "http://localhost:5001/api/v0/diag/net?vis=d3"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: text/plain
Server: go-ipfs/0.4.0-dev
Trailer: X-Stream-Error
X-Stream-Output: 1
Date: Fri, 18 Mar 2016 21:40:17 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
+ links (array)
+ (object)
- source (number)
- target (number)
- value (number)
+ nodes (array)
- (object)
- name (Multihash)
- rtkey (Multihash)
- value (number)
+ Body
```
{
"links": [
{
"source": 0,
"target": 22,
"value": 3
},
...
],
"nodes": [
{
"name": "Qmece2RkXhsKe5CRooNisBTh4SK119KrXXGmoK6V3kb8aH",
"rtkey": "FuYMoHi3adbGrgACqL7tWSQnEVNANZ9NToPo9VTD9VWe",
"value": 10
},
...
]
}
```
+ Request With Vis Option `dot`
#### curl
curl -i "http://localhost:5001/api/v0/diag/net?vis=dot"
+ Body
```
curl -i "http://localhost:5001/api/v0/diag/net?vis=dot"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: text/plain
Server: go-ipfs/0.4.0-dev
Trailer: X-Stream-Error
X-Stream-Output: 1
Date: Fri, 18 Mar 2016 21:40:37 GMT
Transfer-Encoding: chunked
```
+ Attributes (string)
+ Body
```
digraph "diag-net" {
subgraph cluster_L { L [shape=box fontsize=32 label="Nodes: 84\l"] }
N0 [label="Qmece2RkXhsKe5CRooNisBTh4SK119KrXXGmoK6V3kb8aH
23 conns" fontsize=8 shape=box tooltip="Qmece2RkXhsKe5CRooNisBTh4SK119KrXXGmoK6V3kb8aH (23 conns)"]
...
44 conns" fontsize=8 shape=box tooltip="QmavYZiVcX18nfw5fNwrXSUCCDKjWpgaSTG4onHCqTgL5w (44 conns)"]
N0 -> N37 [label=" 67442950" weight=1 tooltip="Qmece2RkXhsKe5CRooNisBTh4SK119KrXXGmoK6V3kb8aH ... Qmda2AecGMjJ96P7tgcyveEx7EDWF4JghPfr2jAW7ov6HG (67442950)" labeltooltip="Qmece2RkXhsKe5CRooNisBTh4SK119KrXXGmoK6V3kb8aH ... Qmda2AecGMjJ96P7tgcyveEx7EDWF4JghPfr2jAW7ov6HG (67442950)" style="dotted"]
...
```
## sys [GET /diag/sys]
Print out information about your computer to aid in debugging.
+ Request
#### curl
curl -i http://localhost:5001/api/v0/diag/sys
+ Body
```
curl -i http://localhost:5001/api/v0/diag/sys
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.2
Trailer: X-Stream-Error
Vary: Origin
Date: Sun, 19 Jun 2016 14:24:40 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
- diskinfo (object)
- free_space: 6639185920 (number)
- fstype: hfs (string)
- total_space: 120101797888 (number)
- environment (object)
- GOPATH: "/Users/dignifiedquire/.go" (string)
- IPFS_PATH (string, nullable)
- ipfs_commit: "a6fb581" (string, nullable)
- ipfs_version: "0.3.9" (string)
- memory (object)
- swap: 0 (number)
- virt: 0 (number)
- net (object)
- interface_addresses (array)
- "/ip6/::1" (MultiAddr)
- online (boolean)
- runtime (object)
- arch: amd64 (string)
- compiler: gc (string)
- gomaxprocs: 3 (number)
- numcpu: 4 (number)
- numgoroutines: 145 (number)
- os: darwin (string)
- version: `go1.5.1` (string)
+ Body
```
{
"diskinfo": {
"free_space": 22129876992,
"fstype": "17",
"total_space": 21867732992
},
"environment": {
"GOPATH": "/Users/richard/gocode",
"IPFS_PATH": ""
},
"ipfs_commit": "a6fb581",
"ipfs_version": "0.4.2",
"memory": {
"swap": 0,
"virt": 0
},
"net": {
"interface_addresses": [
"/ip6/::1",
"/ip4/127.0.0.1",
"/ip6/fe80::1",
"/ip6/fe80::a6d1:8cff:fee0:7950",
"/ip4/192.168.10.234",
"/ip6/fe80::6c24:b1ff:fe6d:8ad2"
],
"online": true
},
"runtime": {
"arch": "amd64",
"compiler": "gc",
"gomaxprocs": 3,
"numcpu": 4,
"numgoroutines": 211,
"os": "darwin",
"version": "go1.5.3"
}
}
```
# Group dns
DNS link resolver.
## dns [GET /dns{?arg}]
Multihashes are hard to remember, but domain names are usually easy to
remember. To create memorable aliases for multihashes, DNS TXT
records can point to other DNS links, IPFS objects, IPNS keys, etc.
This command resolves those links to the referenced object.
+ Parameters
+ arg (string, required) - DNS name
+ recursive (string, optional) - Resolve until the result is not a DNS link. Default: false.
+ Request Without Arguments
#### curl
curl -i "http://localhost:5001/api/v0/dns"
+ Body
```
curl -i "http://localhost:5001/api/v0/dns"
```
+ Response 400
+ Headers
```
Date: Fri, 05 Feb 2016 23:30:20 GMT
Content-Length: 34
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
+ Body
```
Argument 'domain-name' is required
```
+ Request With Empty Argument
The response is the same if the argument is invalid. For example:
curl -i "http://localhost:5001/api/v0/dns?arg=kitten"
#### curl
curl -i "http://localhost:5001/api/v0/dns?arg="
+ Body
```
curl -i "http://localhost:5001/api/v0/dns?arg="
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 17:01:03 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "not a valid domain name"
- Code: 0
+ Body
```
{
"Message": "not a valid domain name",
"Code": 0
}
```
+ Request With Argument
#### curl
curl -i "http://localhost:5001/api/v0/dns?arg=ipfs.io"
+ Body
```
curl -i "http://localhost:5001/api/v0/dns?arg=ipfs.io"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 17:01:14 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
- Path (string)
+ Body
```
{
"Path": "/ipfs/QmUbFnoqVhzPBXq1Bi2Rn9dCYu1csbKuowo7oTj5FCdXQs""
}
```
+ Request With Valid Argument And No Recursive Option
#### curl
curl -i "http://localhost:5001/api/v0/dns?arg=recursive.ipfs.io"
+ Body
```
curl -i "http://localhost:5001/api/v0/dns?arg=recursive.ipfs.io"
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 17:01:23 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Code: 0
- Message: "Could not resolve name. Recursion limit exceeded."
+ Body
```
{
"Code": 0,
"Message": "Could not resolve name (recursion limit exceeded)."
}
```
+ Request With Valid Argument And Recursive Option
#### curl
curl -i "http://localhost:5001/api/v0/dns?arg=recursive.ipfs.io&r"
+ Body
```
curl -i "http://localhost:5001/api/v0/dns?arg=recursive.ipfs.io&r"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 17:01:37 GMT
Transfer-Encoding: chunked
```
+ Attributes (object)
- Path (string)
+ Body
```
{
"Path": "/ipfs/QmUbFnoqVhzPBXq1Bi2Rn9dCYu1csbKuowo7oTj5FCdXQs"
}
```
# Group file
Interact with IPFS objects representing Unix filesystems.
This provides a familiar interface to file systems represented
by IPFS objects, which hides IPFS implementation details like layout
objects (e.g. fanout and chunking).
This command can't be called directly.
## ls [GET /file/ls{?arg}]
List directory contents for Unix filesystem object
Retrieves the object named by <ipfs-or-ipns-path> and displays the
contents.
The JSON output contains size information. For files, the child size
is the total size of the file contents. For directories, the child
size is the IPFS link size.
The path can be a prefixless ref; in this case, we assume it to be an
/ipfs ref and not /ipns.
+ Parameters
+ arg (string, required) - The path to the IPFS object or objects to list links from.
+ Request Without Arguments
#### curl
curl -i "http://localhost:5001/api/v0/file/ls"
+ Body
```
curl -i "http://localhost:5001/api/v0/file/ls"
```
+ Response 400
+ Headers
```
Date: Sat, 06 Feb 2016 23:13:03 GMT
Content-Length: 32
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
+ Body
```
Argument 'ipfs-path' is required
```
+ Request With Empty Argument
The response is the same if the argument is invalid. For example:
curl -i "http://localhost:5001/api/v0/file/ls?arg=kitten"
#### curl
curl -i "http://localhost:5001/api/v0/file/ls?arg="
+ Body
```
curl -i "http://localhost:5001/api/v0/file/ls?arg="
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 17:02:27 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "invalid ipfs ref path"
- Code: 0
+ Body
```
{
"Message": "invalid ipfs ref path",
"Code": 0
}
```
+ Request With Argument
#### curl
curl -i "http://localhost:5001/api/v0/file/ls?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ"
+ Body
```
curl -i "http://localhost:5001/api/v0/file/ls?arg=QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1
Trailer: X-Stream-Error
Date: Thu, 28 Apr 2016 17:02:37 GMT
Transfer-Encoding: chunked
```
+ Attributes
+ Argument (object)
- Key (Multihash) - Where 'Key' is the IPFS object's multihash.
+ Objects (object)
+ Key (object) - Where 'Key' is the IPFS object's multihash.
- Hash (Multihash)
- Size (number)
- Type (string)
- Links (array)
- (object)
- Name (string)
- Hash (Multihash)
- Size (number)
- Type (string)
+ Body
```
{
"Arguments": {
"QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ": "QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ"
},
"Objects": {
"QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ": {
"Hash": "QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ",
"Size": 0,
"Type": "Directory",
"Links": [
{
"Name": "cat.jpg",
"Hash": "Qmd286K6pohQcTKYqnS1YhWrCiS4gz7Xi34sdwMe9USZ7u",
"Size": 443230,
"Type": "File"
}
]
}
}
}
```
# Group files
Manipulate unixfs files.
Files is an API for manipulating ipfs objects as if they were a unix filesystem.
Note:
Most of the subcommands of 'ipfs files' accept the 'flush' option. It defaults to
'true'. Use caution when setting this to 'false'. It will improve performance
for large numbers of file operations, but it does so at the cost of consistency
guarantees.
This command can't be called directly.
## rm [POST /files/rm{?arg}{&recursive,flush}]
Remove a file.
### Bugs
+ Parameters
+ arg (string, required) - File to remove.
+ recursive (boolean, optional) - Recursively remove directories. Default: false. Alias: r.
+ flush (boolean, optional) - Flush target and ancestors after write. Default: true. Alias: f.
+ Request Without Arguments
#### curl
curl -i -X POST "http://localhost:5001/api/v0/files/rm"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/files/rm"
```
+ Response 400
+ Headers
```
Date: Fri, 19 Feb 2016 15:02:04 GMT
Content-Length: 27
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
+ Body
```
Argument 'path' is required
```
+ Request With Empty Argument
#### curl
curl -i -X POST "http://localhost:5001/api/v0/files/rm?arg="
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/files/rm?arg="
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 16:42:51 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "Paths must not be empty."
- Code: 0
+ Body
```
{
"Code": 0,
"Message": "Paths must not be empty."
}
```
+ Request With Invalid Argument
#### curl
curl -i -X POST "http://localhost:5001/api/v0/files/rm?arg=kitten"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/files/rm?arg=kitten"
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 16:43:04 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "Paths must start with a leading slash."
- Code: 0
+ Body
```
{
"Code": 0,
"Message": "Paths must start with a leading slash."
}
```
+ Request With Argument
This request is dependent on there being a 'test' file in your Files API folder.
To create this file, run:
url -i "http://localhost:5001/api/v0/files/cp?arg=/ipfs/QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o&arg=/test"
#### curl
curl -i -X POST "http://localhost:5001/api/v0/files/rm?arg=/test"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/files/rm?arg=/test"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 18:41:36 GMT
Transfer-Encoding: chunked
```
+ Attributes (string)
+ Body
```
```
+ Request With Argument For Directory Without Recursive
'/test' here must be a directory, not a file.
To create this folder, run:
curl -i "http://localhost:5001/api/v0/files/mkdir?arg=/test"
#### curl
curl -i -X POST "http://localhost:5001/api/v0/files/rm?arg=/test"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/files/rm?arg=/test"
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 18:42:34 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "/test is a directory, use -r to remove directories"
- Code: 0
+ Body
```
{
"Code": 0,
"Message": "/test is a directory, use -r to remove directories"
}
```
+ Request With Argument And Recursive Option
This request is dependent on there being a 'test' folder in your Files API folder.
To create this folder, run:
curl -i "http://localhost:5001/api/v0/files/mkdir?arg=/test"
#### curl
curl -i -X POST "http://localhost:5001/api/v0/files/rm?arg=/test&recursive"
+ Body
```
curl -i -X POST "http://localhost:5001/api/v0/files/rm?arg=/test&recursive"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 18:42:48 GMT
Transfer-Encoding: chunked
```
+ Attributes (string)
+ Body
```
```
## flush [GET /files/flush{?arg}{&flush}]
Flush a given path's data to disk.
This is only useful when other commands
are run with the 'flush' option set to false.
+ Parameters
+ arg (string, required) - Path to flush. Default: '/'.
+ Request Without Arguments
#### curl
curl -i "http://localhost:5001/api/v0/files/flush"
+ Body
```
curl -i "http://localhost:5001/api/v0/files/flush"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 18:43:15 GMT
Transfer-Encoding: chunked
```
+ Attributes (string)
+ Body
```
```
+ Request With Empty Argument
#### curl
curl -i "http://localhost:5001/api/v0/files/flush?arg="
+ Body
```
curl -i "http://localhost:5001/api/v0/files/flush?arg="
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 18:43:25 GMT
Transfer-Encoding: chunked
```
+ Attributes (string)
+ Body
```
```
+ Request With Invalid Argument
#### curl
curl -i "http://localhost:5001/api/v0/files/flush?arg=kitten"
+ Body
```
curl -i "http://localhost:5001/api/v0/files/flush?arg=kitten"
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 18:43:35 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "file does not exist"
- Code: 0
+ Body
```
{
"Code": 0,
"Message": "file does not exist"
}
```
+ Request With Argument
#### curl
curl -i "http://localhost:5001/api/v0/files/flush?arg=/test"
+ Body
```
curl -i "http://localhost:5001/api/v0/files/flush?arg=/test"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 18:43:46 GMT
Transfer-Encoding: chunked
```
+ Attributes (string)
+ Body
```
```
## mv [GET /files/mv{?arg,arg2}{&flush}]
Move files.
Move files around. Just like traditional unix mv.
+ Parameters
+ arg (string, required) - Source file to move.
+ arg2 (string, required) - Target path for file to be moved to.
+ flush (boolean, optional) - Flush target and ancestors after write. Default: true. Alias: f.
+ Request Without Arguments
#### curl
curl -i "http://localhost:5001/api/v0/files/mv"
+ Body
```
curl -i "http://localhost:5001/api/v0/files/mv"
```
+ Response 400
+ Headers
```
Date: Fri, 19 Feb 2016 16:07:11 GMT
Content-Length: 29
Content-Type: text/plain; charset=utf-8
```
+ Attributes (string)
+ Body
```
Argument 'source' is required
```
+ Request With Empty Arguments
#### curl
curl -i "http://localhost:5001/api/v0/files/mv?arg=&arg="
+ Body
```
curl -i "http://localhost:5001/api/v0/files/mv?arg=&arg="
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 18:44:04 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "Paths must not be empty."
- Code: 0
+ Body
```
{
"Code": 0,
"Message": "Paths must not be empty."
}
```
+ Request With Invalid Argument
#### curl
curl -i "http://localhost:5001/api/v0/files/mv?arg=kitten&arg=kitten"
+ Body
```
curl -i "http://localhost:5001/api/v0/files/mv?arg=kitten&arg=kitten"
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 18:44:21 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Message: "Paths must start with a leading slash."
- Code: 0
+ Body
```
{
"Code": 0,
"Message": "Paths must start with a leading slash."
}
```
+ Request With Non-Existent Argument
This call depends upon a file in the Files API called 'here'. This file must not exist.
To ensure this file does not exist, run:
curl -i "http://localhost:5001/api/v0/files/rm?arg=/here"
#### curl
curl -i "http://localhost:5001/api/v0/files/mv?arg=/here&arg=/there"
+ Body
```
curl -i "http://localhost:5001/api/v0/files/mv?arg=/here&arg=/there"
```
+ Response 500
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 18:44:54 GMT
Transfer-Encoding: chunked
```
+ Attributes (Error)
- Code: 0
- Message: "file does not exist"
+ Body
```
{
"Code": 0,
"Message": "file does not exist"
}
```
+ Request With Argument
This call depends upon a file in the Files API called 'here'. To create such a file, run:
curl -i "http://localhost:5001/api/v0/files/cp?arg=/ipfs/QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o&arg=/here"
#### curl
curl -i "http://localhost:5001/api/v0/files/mv?arg=/here&arg=/there"
+ Body
```
curl -i "http://localhost:5001/api/v0/files/mv?arg=/here&arg=/there"
```
+ Response 200
+ Headers
```
Access-Control-Allow-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Access-Control-Expose-Headers: X-Stream-Output, X-Chunked-Output, X-Content-Length
Content-Type: application/json
Server: go-ipfs/0.4.1-dev
Trailer: X-Stream-Error
Date: Tue, 19 Apr 2016 18:46:03 GMT
Transfer-Encoding: chunked
```
+ Attributes (string)
+ Body
```
```
## cp [GET /files/cp{?arg,arg2}{&flush}]
Copy files into mfs.
+ Parameters
+ arg (string, required) - Source file to move.
+ arg2 (string, required) - Destination to copy object to.
+ flush (boolean, optional) - Flush target and ancestors after write. Default: true. Alias: f.
+ Request Without Arguments
#### curl
curl -i "http://localhost:5001/api/v0/files/cp"
+ Body
```
curl -i "http://localhost:5001/api/v0/files/cp"
```
+ Response 400
</