diff --git a/API/pinning-api/README.md b/API/pinning-api/README.md
index c08c3c27..99e1ca7d 100644
--- a/API/pinning-api/README.md
+++ b/API/pinning-api/README.md
@@ -1,9 +1,9 @@
-pinning API
-===========
+Pin API
+=======
 
 #### `add`
 
-> Pin an IPFS object to local storage
+> Adds an IPFS object to the pinset and also stores it to the IPFS repo. pinset is the set of hashes currently pinned (not gc'able).
 
 ##### `Go` **WIP**
 
@@ -12,10 +12,17 @@ pinning API
 Where:
 
 - `hash` is an IPFS multihash.
-- `options` is an object that can contain the following keys:
-  - `recursive` - Recursevely pin the object linked.
+- `options` is an object that can contain the following keys
+  - `recursive` - Recursively pin the object linked. Type: bool. Default: 'false'
+
+`callback` must follow `function (err, res) {}` signature, where `err` is an error if the operation was not successful. `res` is an array of objects that represent the files that were pinned. Example:
 
-`callback` must follow `function (err) {}` signature, where `err` is an error if the operation was not successful.
+```JavaScript
+{
+  hash: 'QmHash',
+  path: 'some-path
+}
+``` 
 
 If no `callback` is passed, a promise is returned.
 
@@ -37,7 +44,7 @@ Where:
 
 - `hash` is an IPFS multihash.
 - `options` is an object that can contain the following keys:
-  - `type` - Return also the type of pin (direct, indirect or recursive)
+  - 'type' - Return also the type of pin (direct, indirect or recursive)
 
 `callback` must follow `function (err, pinset) {}` signature, where `err` is an error if the operation was not successful. `pinset` is an array of objects with keys `hash` and `type`.
 
@@ -52,13 +59,16 @@ ipfs.pin.ls(function (err, pinset) {})
 
 #### `rm`
 
-> Remove an hash from the pinset
+> Remove a hash from the pinset
 
 ##### `Go` **WIP**
 
-##### `JavaScript` - ipfs.pin.rm(hash, [callback])
+##### `JavaScript` - ipfs.pin.rm(hash, [options, callback])
 
-Where `hash` is a multihash.
+Where:
+- `hash` is a multihash.
+- `options` is an object that can contain the following keys
+  - `recursive` - Recursively unpin the object linked. Type: bool. Default: 'false'
 
 `callback` must follow `function (err) {}` signature, where `err` is an error if the operation was not successful. 
 
diff --git a/package.json b/package.json
index 5b437904..b3750513 100644
--- a/package.json
+++ b/package.json
@@ -47,4 +47,4 @@
     "greenkeeperio-bot <support@greenkeeper.io>",
     "nginnever <ginneversource@gmail.com>"
   ]
-}
\ No newline at end of file
+}
diff --git a/src/index.js b/src/index.js
index 33c4ad49..38d0b50b 100644
--- a/src/index.js
+++ b/src/index.js
@@ -3,3 +3,4 @@
 exports.object = require('./object')
 exports.files = require('./files')
 exports.config = require('./config')
+exports.pin = require('./pin')
diff --git a/src/pin.js b/src/pin.js
new file mode 100644
index 00000000..92d53e7f
--- /dev/null
+++ b/src/pin.js
@@ -0,0 +1,133 @@
+/* eslint-env mocha */
+/* eslint max-nested-callbacks: ["error", 8] */
+
+'use strict'
+
+const expect = require('chai').expect
+const fs = require('fs')
+const path = require('path')
+
+const testfile = fs.readFileSync(path.join(__dirname, './data/testfile.txt'))
+
+module.exports = (common) => {
+  describe('.pin', () => {
+    let ipfs
+
+    before(function (done) {
+      // CI is slow
+      this.timeout(20 * 1000)
+
+      common.setup((err, factory) => {
+        expect(err).to.not.exist
+        factory.spawnNode((err, node) => {
+          expect(err).to.not.exist
+          ipfs = node
+          done()
+        })
+      })
+    })
+
+    after((done) => {
+      common.teardown(done)
+    })
+
+    it('add file for testing', (done) => {
+      const expectedMultihash = 'Qma4hjFTnCasJ8PVp3mZbZK5g2vGDT4LByLJ7m8ciyRFZP'
+
+      ipfs.files.add(testfile, (err, res) => {
+        expect(err).to.not.exist
+
+        expect(res).to.have.length(1)
+        expect(res[0].hash).to.equal(expectedMultihash)
+        expect(res[0].path).to.equal(expectedMultihash)
+        done()
+      })
+    })
+
+    describe('callback API', () => {
+      it('.rm (1st, because ipfs.files.add pins automatically)', (done) => {
+        const hash = 'Qma4hjFTnCasJ8PVp3mZbZK5g2vGDT4LByLJ7m8ciyRFZP'
+
+        ipfs.pin.rm(hash, { recursive: true }, (err, res) => {
+          expect(err).to.not.exist
+          expect(res).to.exist
+          ipfs.pin.ls({ type: 'direct' }, (err, res) => {
+            expect(err).to.not.exist
+            expect(res).to.exist
+            expect(res.Keys).to.be.empty
+            done()
+          })
+        })
+      })
+
+      it('.add', (done) => {
+        const hash = 'Qma4hjFTnCasJ8PVp3mZbZK5g2vGDT4LByLJ7m8ciyRFZP'
+
+        ipfs.pin.add(hash, { recursive: false }, (err, res) => {
+          expect(err).to.not.exist
+          expect(res.Pins[0]).to.be.equal(hash)
+          done()
+        })
+      })
+
+      it('.list', (done) => {
+        ipfs.pin.ls((err, res) => {
+          expect(err).to.not.exist
+          expect(res).to.exist
+          done()
+        })
+      })
+
+      it('.list for a specific hash', (done) => {
+        const hash = 'Qma4hjFTnCasJ8PVp3mZbZK5g2vGDT4LByLJ7m8ciyRFZP'
+
+        ipfs.pin.ls(hash, (err, res) => {
+          expect(err).to.not.exist
+          expect(res).to.exist
+          done()
+        })
+      })
+    })
+
+    describe('promise API', () => {
+      it('.add', () => {
+        const hash = 'Qma4hjFTnCasJ8PVp3mZbZK5g2vGDT4LByLJ7m8ciyRFZP'
+
+        return ipfs.pin.add(hash, { recursive: false })
+          .then((res) => {
+            expect(res.Pins[0]).to.be.equal(hash)
+          })
+      })
+
+      it('.ls', () => {
+        return ipfs.pin.ls()
+          .then((res) => {
+            expect(res).to.exist
+          })
+      })
+
+      it('.ls hash', () => {
+        const hash = 'Qma4hjFTnCasJ8PVp3mZbZK5g2vGDT4LByLJ7m8ciyRFZP'
+
+        return ipfs.pin.ls(hash)
+          .then((res) => {
+            expect(res).to.exist
+          })
+      })
+
+      it('.rm', () => {
+        const hash = 'Qma4hjFTnCasJ8PVp3mZbZK5g2vGDT4LByLJ7m8ciyRFZP'
+
+        return ipfs.pin.rm(hash, { recursive: false })
+          .then((res) => {
+            expect(res).to.exist
+            return ipfs.pin.ls({ type: 'direct' })
+          })
+          .then((res) => {
+            expect(res).to.exist
+            expect(res.Keys).to.be.empty
+          })
+      })
+    })
+  })
+}