apiary.apib

FORMAT: 1A

# ipfs

The API for interacting with IPFS nodes.

# Group add

TODO

# Group bitswap
A set of commands to manipulate the bitswap agent

## stat [GET /bitswap/stat]
Show some diagnostic information on the bitswap agent

+ Response 200 (application/json)

    + Attributes (object)
        + ProvideBufLen: 0 (number)
        + Wantlist (array, nullable)
        + Peers (array)
            - QmNjRVohhWBX31EoaAXkrj5mPF9vQNcTVvQgWHNwdxweCN (Multihash)
        + BlocksReceived: 0 (number)
        + DupBlksReceived: 0 (number)
        + DupDataReceived: 0 (number)

## unwant [GET /bitswap/unwant{?arg}]
Remove a given block from your wantlist

+ Parameters
    + arg (Multihash, required) - key to remove from your wantlist

+ Response 200 (application/json)


## wantlist [GET /bitswap/wantlist{?peer}]
Show blocks currently on the wantlist

+ Parameters
    + peer (Multihash, optional)

        specify which peer to show wantlist for (default self)

+ Response 200 (application/json)

    + Attributes (object)
        + Keys (array, optional)


# Group block
A plumbing command used to manipulate raw ipfs blocks.

## stat [GET /block/stat?{arg}]
Retrieve information on a raw ipfs block.

+ Parameters
    + arg (Multihash, required) - hash of the block to retrieve stats on

+ Response 200 (application/json)

    + Attributes (object)
        + Key: Qmb9Ru8XjPDAokAYE6rVzLwn3dEB4fxijgVMga1CcS95kJ (Multihash)
        + Size: 262158 (number) - the size of the block in bytes

## get [GET /block/get{?arg}]

Store data as a raw ipfs block.

+ Parameters
    + arg (Multihash, required) - hash of the block to be fetched

+ Response 200 (text/plain)

    + Body

        ```
        hello world
        ```

## put [GET /block/put]
TODO


# Group bootstrap
Show or edit the list of bootstrap peers.

Running `ipfs bootstrap` with no arguments will run `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.

## 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

+ Response 200 (application/json)

    + Attributes (object)
        + Peers (array)
            - (Multihash)

    + Body

        ```
        {
          "Peers": [
            "/ip4/5.9.33.222/tcp/4001/ipfs/QmNRV7kyUxYaQ4KzxFXPYm8EfuzJbtGn1wSFenjXL6LD8y"
          ]
        }
        ```

+ Response 400 (application/json)

    + Attributes (object)
        + Message: no bootstrap peers to add (string)
        + Code: 1 (number)

    + Body

        ```
        {
          "Message": "no bootstrap peers to add",
          "Code": 1
        }
        ```

+ Response 500 (application/json)

    + Attributes (object)
        + Message: invalid multiaddr, must begin with / (string)
        + Code: 0 (number)

    + Body

        ```
        {
          "Message": "invalid multiaddr, must begin with /",
          "Code": 0
        }
        ```


## list [GET /bootstrap/list]
Show peers in the bootstrap list

Peers are output in the format `<multiaddr>/<peerID>`.

+ Response 200 (application/json)

    + Attributes (object)
        + Peers (array)
            - (Multihash)
    + 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/QmSoLpPVmHKQ4XTPdz8tjDFgdeRFkpV8JgYq8JVJ69RrZm",
            "/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 (bool, optional) Remove all bootstrap peers.

+ Response 200 (application/json)

    + Attributes (object)
        + Peers (array)
            - (Multihash)

    + Body

        ```
        {
          "Peers": []
        }
        ```

+ Response 500 (application/json)

    + Attributes (object)
        + Message: invalid ipfs address (string)
        + Code: 0 (number)

    + Body

        ```
        {
          "Message": "invalid ipfs address",
          "Code": 0
        }
        ```

# group cat

## cat [GET /cat{?arg}]
Retrieves the object named by <ipfs-or-ipns-path> and outputs the data it contains.

+ Parameters
    + arg (string, required) - The path to the IPFS object(s) to be outputted

+ Response 200

    + Headers
        - Transfer-Encoding: chunked
        - X-Stream-Output: 1

# Group commands

## commands [GET /commands]
Lists all available commands (and subcommands) that are available.

+ Response 200 (application/json)

    + Attributes (object)
        - Name: IPFS (string)
        - Subcommands (array)

# Group config

## edit [GET /config/edit]

+ Response 200 (text/plain)

## replace [GET /config/replace]

+ Response 200 (text/plain)

## show [GET /config/show]

+ Response 200 (text/plain)

# Group daemon

# Group dht

## findpeer [GET /dht/findpeer]

+ Response 200 (text/plain)

## findprovs [GET /dht/findprovs]

+ Response 200 (text/plain)

## get [GET /dht/get]

+ Response 200 (text/plain)

## put [GET /dht/put]

+ Response 200 (text/plain)

## query [GET /dht/query]

+ Response 200 (text/plain)

# Group diag
Generate diagnostic reports.

## 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 network vary.
The default timeout is 20 seconds.

+ Parameters
    + vis (enum[string], optional)
        The d3 format will output a json object ready to be consumed by
        the chord network viewer, available at the following hash:

        ```
        /ipfs/QmbesKpGyQGd5jtJFUGEB1ByPjNFpukhnKZDnkfxUiKn38
        ```

        To view your diag output, 'ipfs add' the d3 vis output, and
        open the following link:

        ```
        http://gateway.ipfs.io/ipfs/QmbesKpGyQGd5jtJFUGEB1ByPjNFpukhnKZDnkfxUiKn38/chord#<your hash>
        ```

        The dot format can be fed into graphviz and other programs
        that consume the dot format to generate graphs of the network.

        + Members
            - `plain text` - easy to read
            - `d3` - json ready to be fed into d3view
            - `dot` - graphviz format


+ Response 200 (text/plain)

    + Body

        ```
        ID QmVnWL4CVWAaQHuuJQMgskDDyFwA1pqA2cC5ZTnQnB5yJt up 60449 seconds connected to 4:
        ID QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx connections: 1 latency: 354632446 ns
        ID QmNeK3hRF5Pu9dPcMDKXvYofQioskuGfQZEQz43UDkLepK connections: 1 latency: 175768996 ns
        ID QmdAYL426boH1RRFR6JABaNT4JNfrEJV1coiPfKytpPVwP connections: 1 latency: 273253825 ns
        ID QmavNkKTvUoE4NaPQZtcmMaxRQqtpbu5jmpTzfH7ScmvHz connections: 1 latency: 157092668 ns
        ```


## sys [GET /diag/sys]
Print out information about your computer to aid in debugging.

+ Response 200 (text/plain)

   + Attributes (object)
       - diskinfo (object)
       - `free_space`: 6639185920 (number)
       - fstype: hfs (string)
       - `total_space`: 120101797888 (number)
       - `used_space`: 113462611968 (number)
       - environment (object)
           - GOPATH: `/Users/dignifiedquire/.go` (string)
           - IPFS_PATH: (string, nullable)
       - `ipfs_git_sha` (string)
       - `ipfs_version`: `0.3.9` (string)
       - memory (object)
           - swap (object)
               - total: 3072000 (number)
               - used: 1935000 (number)
               - free: 1137000 (number)
               - `used_percent`: `62.98828125` (number)
               - sin: 0 (number)
               - sout: 0 (number)
           - virt (object)
               - total: 4294967296 (number)
               - available: 682414080 (number)
               - used: 4277125120 (number)
               - `used_percent`: 84.11130905151367 (number)
               - free: 17842176 (number)
               - active: 671182848 (number)
               - inactive: 664559616 (number)
               - buffers: 0 (number)
               - cached: 664571904 (number)
               - wired: 1469018112 (number)
               - shared: 0 (number)
       - net (object)
       - `interface_addresses` (array)
           - "/ip6/::1" (MultiAddr)
       - 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)

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

The following response expamles assume this DNS TXT record:

```
ipfs.io. TXT "dnslink=/ipfs/QmRzTuh2Lpuz7Gr39stNr6mTFdqAghsZec1JoUnfySUzcy ..."
```

+ Parameters
    + arg (string, required) - DNS name

+ Response 200 (application/json)

    + Attributes (object)
        - Path: `/ipfs/QmTgNJEgQaCqRht9KSXNyZsCp2xpHZmBRms28NRMmtcERp` (Multihash)

# Group file

## ls [GET /file/ls]

+ Response 200 (text/plain)

# Group get

## get [GET /get]

+ Response 200 (text/plain)

# Group id

## id [GET /id]

+ Response 200 (application/json)

    + Attributes (object)
        + ID (Multihash)
        + PublicKey (string)
        + Addresses (array)
            - (Multihash)
        + AgentVersion (string)
        + ProtocolVersion (string)

    + Body

        ```
        {
          "ID": "QmVnWL4CVWAaQHuuJQMgskDDyFwA1pqA2cC5ZTnQnB5yJt",
          "PublicKey": "CAASpgIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQD8SKPSPmQp3VJJmAaOsXnNU1Qqvz/TeBFO9VeoVDAD4gapupBBUZC5f2eTnWKXMiZt7m21xSzJ5i+G16uFCY1296maoas648C66XuxxwDpf4B/K/A2C6mjqQzKgrAZDiD9WS0oS2wsGlaEbikX/KXOw9PJOYThC4zvGHoQnYqmdXiXvNbtV9ZsjpkdU420kj4FQGcti7WvAukXX2yvVsxmnDLvpFFiNY96OkFAItZhvcROXB69davEL5Uthl90gR2d+nunBPTJeO/yZUk2mtcoB9Y0Q//qnLnGY2VlZkpVBjUpq2BLWUDu72BGRsxF+QU+MHqai5lJn73MZNQl3kOVAgMBAAE=",
          "Addresses": [
            "/ip4/127.0.0.1/tcp/4001/ipfs/QmVnWL4CVWAaQHuuJQMgskDDyFwA1pqA2cC5ZTnQnB5yJt",
            "/ip4/192.168.0.11/tcp/4001/ipfs/QmVnWL4CVWAaQHuuJQMgskDDyFwA1pqA2cC5ZTnQnB5yJt",
            "/ip6/::1/tcp/4001/ipfs/QmVnWL4CVWAaQHuuJQMgskDDyFwA1pqA2cC5ZTnQnB5yJt",
            "/ip6/fd67:d185:7678:b25b:3cd6:bb15:ff71:af88/tcp/4001/ipfs/QmVnWL4CVWAaQHuuJQMgskDDyFwA1pqA2cC5ZTnQnB5yJt",
            "/ip4/85.216.106.69/tcp/4001/ipfs/QmVnWL4CVWAaQHuuJQMgskDDyFwA1pqA2cC5ZTnQnB5yJt",
            "/ip4/85.216.106.69/tcp/60505/ipfs/QmVnWL4CVWAaQHuuJQMgskDDyFwA1pqA2cC5ZTnQnB5yJt",
            "/ip4/85.216.106.69/tcp/60505/ipfs/QmVnWL4CVWAaQHuuJQMgskDDyFwA1pqA2cC5ZTnQnB5yJt"
            ],
          "AgentVersion": "go-ipfs/0.3.9",
          "ProtocolVersion": "ipfs/0.1.0"
        }
        ```

# Group log

## level [GET /log/level]

+ Response 200 (text/plain)

## tail [GET /log/tail]

+ Response 200 (text/plain)

# Group ls

## ls [GET /ls]

+ Response 200 (text/plain)

# Group mount
Mount ipfs at a read-only mountpoint on the OS (default: /ipfs and /ipns).
All ipfs objects will be accessible under that directory. Note that the
root will not be listable, as it is virtual. Access known paths directly.

+ Response 200 (application/json)

# Group name

## publish [GET /name/publish]

+ Response 200 (text/plain)

## resolve [GET /name/resolve]

+ Response 200 (text/plain)

# Group object
Interact with ipfs objects.

## data [GET /object/data]

+ Response 200 (text/plain)

## get [GET /object/get]

+ Response 200 (text/plain)

## links [GET /object/links]

+ Response 200 (text/plain)

## new [GET /object/new]

+ Response 200 (text/plain)

## patch [GET /object/patch]

+ Response 200 (text/plain)

## put [GET /object/put]

+ Response 200 (text/plain)

## stat [GET /object/stat]

+ Response 200 (text/plain)

# Group pin
## add [GET /pin/add]

+ Response 200 (text/plain)

## ls [GET /pin/ls]

+ Response 200 (text/plain)

## rm [GET /pin/rm]

+ Response 200 (text/plain)

# Group ping
Send echo request packets to IPFS hosts

## ping [GET /ping]
A tool to test sending data to other nodes. It finds nodes
via the routing system, send pings, wait for pongs, and print out round-
trip latency information.

+ Response 200 (application/json)
    + Headers

        ```
        X-Chunked-Output: 1
        ```

    + Body

        ```
        {
          "Success": false,
          "Time": 0,
          "Text": "PING QmSqn9NJaPrdvDRQxUC2FMQWjJQnvbjUuMoXvA8hm5Nx1b."
        }
        {
          "Success": true,
          "Time": 113267897,
          "Text": ""
        }
        {
          "Success": true,
          "Time": 56161127,
          "Text": ""
        }
        ```

# Group refs

## local [GET /refs/local]

+ Response 200 (text/plain)


# Group repo
Manipulate the IPFS repo.

## gc [GET /repo/gc]
Sweep the local set of stored objects and remove ones that are not pinned in
order to reclaim hard disk space.

+ Response 200 (text/plain)


# Group resolve
Resolve the value of names to IPFS.

## resolve [GET /resolve]
There are a number of mutable name protocols that can link among
themselves and into IPNS.  For example IPNS references can (currently)
point at IPFS object, and DNS links can point at other DNS links, IPNS
entries, or IPFS objects. This command accepts any of these
identifiers and resolves them to the referenced item.

+ Response 200 (application/json)

    + Attributes (object)
        - Path: `/ipfs/QmeuehsX78RCnHnqxq9o7A1pC5ShrtAcDE3pzwyWjXzeZF` (MultiAddr)

# Group stats
Query IPFS statistics.

## bw [GET /stats/bw]
Print ipfs bandwidth information.

+ Response 200 (application/json)

    + Attributes (object)
        - TotalIn: 119395 (number)
        - TotalOut: 47349 (number)
        - RateIn: `296.8016259649661` (number)
        - RateOut: `199.70053032537362` (number)


# Group swarm
Swarm inspection tool.

## addrs [GET /swarm/addrs]
List known addresses. Useful for debugging.

+ Response 200 (application/json)

    + Attributes (object)
        - Addrs (SwarmAddrs)

## addrs local [GET /swarm/addrs/local]
List all local addresses.

+ Response 200 (application/json)

    + Attributes (object)
        - Strings (array)
            - "/ip4/127.0.0.1/tcp/4001" (MultiAddr)

## connect [GET /swarm/connect{?arg}]
Open a connection to the given address.

+ Parameters
    + arg (MultiAddr, required) - Address of the peer to connect to

+ Response 200 (text/plain)


## disconnect [GET /swarm/disconnect{?arg}]
Close the connection to a given address.

+ Parameters
    + arg (MultiAddr, required) - Address of the peer to disconnect from

+ Response 200 (text/plain)

## filters [GET /swarm/filters]
List out all currently applied filters. The subcommands can be used
to add or remove said filters. Filters are specified using the multiaddr-filter format:

**Example:**

```
/ip4/192.168.0.0/ipcidr/16
```

Where the above is equivalent to the standard CIDR:

```
192.168.0.0/16
```

Filters default to those specified under the `"Swarm.AddrFilters"` config key.

+ Response 200 (application/json)

    + Attributes (object)
        - Strings (array)
            - "/ip4/192.168.0.0/ipcidr/16" (MultiAddr)


## filters add [GET /swarm/filters/add{?arg}]
Add the given multiaddr to the filter list.

+ Parameters
    + arg (MultiAddr, required) - Address to add to the filter list

+ Response 200 (application/json)

## filters rm [GET /swarm/filters/rm{?arg}]
Remove the given multiaddr from the filter list.

+ Parameters
    + arg (MultiAddr, required) - Address to remove from the filter list

+ Response 200 (application/json)

## peers [GET /swarm/peers]
List the set of peers the node is connected to.

+ Response 200 (application/json)

    + Attributes (object)
        - Strings (array)
            - "/ip4/104.233.87.68/tcp/55125/ipfs/QmdAYL426boH1RRFR6JABaNT4JNfrEJV1coiPfKytpPVwP" (MultiAddr)

# Group tar
Utility functions for tar files in ipfs

## add [GET /tar/add]
Import a tar file into ipfs

+ Response 200 (text/plain)

## cat [GET /tar/cat]
Export a tar file from ipfs

+ Response 200 (text/plain)

# Group tour
This is a tour that takes you through various IPFS concepts,
features, and tools to make sure you get up to speed with
IPFS very quickly.

## tour [GET /tour{?arg}]

Start the tour

+ Parameters
    + arg (string, optional) - Topic id to go to

+ Response 200 (text/plain)

    + Body

        ```
        - * 0.0   Hello Mars
        -   0.1   Hello Mars
        -   0.2   About IPFS
        -   1.1   Filesystem
        -   1.2   Getting Files
        -   1.3   Adding Files
        -   1.4   Directories
        -   1.5   Distributed
        -   1.6   Getting Files
        -   2.0   Basics - init
        -   2.1   Basics - help
        -   2.2   Basics - update
        -   2.3   Basics - config
        ```

## list [GET /tour/list]
Show a list of all tour topics.

+ Response 200 (text/plain)

    + Body

        ```
        Tour 0.0 - Hello Mars
        ```


## next [GET /tour/next]
Show the next tour topic.

+ Response 200 (text/plain)

    + Body

        ```
        Tour 0.1 - Hello Mars
        ```

## restart [GET /tour/restart]
Restart the IPFS Tour

+ Response 200 (application/json)

# Group version
Show version details about the ipfs node.

## version [GET /version]

+ Response 200 (application/json)
    + Attributes (object)
        - Version: `0.3.9` (string)
        - Commit: b036b23a233a64faa6a456522b0f45763be70e64 (string)

# Data Structures

## Multihash (string)
An hash as defined [here](https://github.com/jbenet/multihash)

### Sample
QmNjRVohhWBX31EoaAXkrj5mPF9vQNcTVvQgWHNwdxweCN


## SwarmAddrs (object)
A list of swarm addresses.

### Sample
```
"QmNRCEwFMgCcbjNk5bFud9oqjJduvjBNbkiM8SuxuLh3GS": [
  "/ip4/127.0.0.1/tcp/4001",
  "/ip4/172.17.42.1/tcp/4001",
  "/ip4/192.168.2.3/tcp/4001",
  "/ip6/::1/tcp/4001"
],
"QmNRV7kyUxYaQ4KQxFXPYm8EfuzJbtGn1wSFenjXL6LD8y": [
  "/ip4/127.0.0.1/tcp/4001",
  "/ip4/172.17.42.1/tcp/4001",
  "/ip4/5.9.33.222/tcp/4001",
  "/ip6/2a01:4f8:161:124a::1337:cafe/tcp/4001",
  "/ip6/2a01:4f8:161:124a::2/tcp/4001",
  "/ip6/::1/tcp/4001",
  "/ip6/fcfc:762a:e12a:245d:8e5b:6a40:f65:acab/tcp/4001"
]
```


## MultiAddr (string)
A multiaddr as defined [here](https://github.com/jbenet/multiaddr).

### Sample
`/ip6/fcfc:762a:e12a:245d:8e5b:6a40:f65:acab/tcp/4001`