diff --git a/README.md b/README.md
index 56ed41e4a..cece4204e 100644
--- a/README.md
+++ b/README.md
@@ -61,12 +61,49 @@ If are using this module in a browser with something like browserify, then you w
 $ ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin "[\"http://example.com\"]"
 ```
 
-## API
+## Usage
 
-### Level 1 Commands
-Level 1 commands are simple commands
+We classify the API calls by 'core', 'extensions', 'tooling', and 'network', following the same API spec organization available at [ipfs/specs](https://github.com/ipfs/specs/blob/ipfs/api/api/core/README.md)
 
-#### add
+The tests folder also contains great examples that can be used to understand how this client library interacts with the HTTP-API. You can find the tests here: https://github.com/ipfs/js-ipfs-api/tree/master/test/api
+
+### Core
+
+##### Block
+
+##### Object
+
+**Curl**
+```sh
+curl 'http://localhost:5001/api/v0/object/get?arg=QmYEqnfCZp7a39Gxrgyv3qRS4MoCTGjegKV6zroU3Rvr52&stream-channels=true' --compressed
+```
+
+**Response**
+```js
+{
+    Links: [{
+        Name: string,
+        Hash: string,
+        Size: number
+    }, ...],
+    Data: string
+}
+```
+*Data is base64 encoded.*
+
+##### Pin
+
+
+-------------------------------------------------------
+
+### Extensions
+
+
+-------------------------------------------------------
+
+### Tooling
+
+##### add
 
 Add a file (where file is any data) to ipfs returning the hash and name. The
 name value will only be set if you are actually sending a file. A single or
@@ -83,6 +120,7 @@ ipfs.add(files, function(err, res) {
     })
 })
 ```
+
 `files` can be a mixed array of filenames or buffers of data. A single value is
 also acceptable.
 
@@ -111,11 +149,12 @@ curl 'http://localhost:5001/api/v0/add?stream-channels=true' \
 
 
 
-#### cat
+##### cat
 
 Retrieve the contents of a single hash, or array of hashes.
 
 **Usage**
+
 ```javascript
 ipfs.cat(hashs, function(err, res) {
     if(err || !res) return console.error(err)
@@ -131,6 +170,7 @@ ipfs.cat(hashs, function(err, res) {
 ```
 
 **Curl**
+
 ```sh
 curl "http://localhost:5001/api/v0/cat?arg=<hash>&stream-channels=true"
 ```
@@ -139,7 +179,7 @@ curl "http://localhost:5001/api/v0/cat?arg=<hash>&stream-channels=true"
 
 The response is either a readable stream, or a string.
 
-#### ls
+##### ls
 Get the node structure of a hash. Included in it is a hash and array to links.
 
 **Usage**
@@ -179,46 +219,12 @@ curl "http://localhost:5001/api/v0/ls?arg=<hash>&stream-channels=true"
 }
 ```
 
+##### Update
 
-**version**
-
-**commands**
-
-### Level 2 Commands
-Level 2 commands are simply named spaced wrapped commands
-
-#### Config
-
-#### Update
-
-#### Mount
-
-#### Diag
-
-#### Block
-
-#### Object
-
-**Curl**
-```sh
-curl 'http://localhost:5001/api/v0/object/get?arg=QmYEqnfCZp7a39Gxrgyv3qRS4MoCTGjegKV6zroU3Rvr52&stream-channels=true' --compressed
-```
+-------------------------------------------------------
 
-**Response**
-```js
-{
-    Links: [{
-        Name: string,
-        Hash: string,
-        Size: number
-    }, ...],
-    Data: string
-}
-```
-*Data is base64 encoded.*
+### Network
 
-#### Swarm
 
-#### Pin
 
-#### Gateway
+-------------------------------------------------------
diff --git a/examples/add.js b/examples/add.js
deleted file mode 100644
index be3fdedd4..000000000
--- a/examples/add.js
+++ /dev/null
@@ -1,22 +0,0 @@
-'use strict'
-
-var ipfs = require('../src')('localhost', 5001)
-
-var f1 = 'Hello'
-var f2 = 'World'
-
-ipfs.add([new Buffer(f1), new Buffer(f2)], function (err, res) {
-  if (err || !res) return console.log(err)
-
-  for (var i = 0; i < res.length; i++) {
-    console.log(res[i])
-  }
-})
-
-ipfs.add(['./files/hello.txt', './files/ipfs.txt'], function (err, res) {
-  if (err || !res) return console.log(err)
-
-  for (var i = 0; i < res.length; i++) {
-    console.log(res[i])
-  }
-})
diff --git a/examples/cat.js b/examples/cat.js
deleted file mode 100644
index d24aa5a2d..000000000
--- a/examples/cat.js
+++ /dev/null
@@ -1,18 +0,0 @@
-'use strict'
-
-var ipfs = require('../src')('localhost', 5001)
-
-var hash = [
-  'QmdFyxZXsFiP4csgfM5uPu99AvFiKH62CSPDw5TP92nr7w',
-  'QmY9cxiHqTFoWamkQVkpmmqzBrY3hCBEL2XNu3NtX74Fuu'
-]
-
-ipfs.cat(hash, function (err, res) {
-  if (err || !res) return console.log(err)
-
-  if (res.readable) {
-    res.pipe(process.stdout)
-  } else {
-    console.log(res)
-  }
-})
diff --git a/examples/files/hello.txt b/examples/files/hello.txt
deleted file mode 100644
index e965047ad..000000000
--- a/examples/files/hello.txt
+++ /dev/null
@@ -1 +0,0 @@
-Hello
diff --git a/examples/files/ipfs.txt b/examples/files/ipfs.txt
deleted file mode 100644
index 95a311652..000000000
--- a/examples/files/ipfs.txt
+++ /dev/null
@@ -1 +0,0 @@
-IPFS
diff --git a/examples/ipfs-add.js b/examples/ipfs-add.js
deleted file mode 100755
index 572791db2..000000000
--- a/examples/ipfs-add.js
+++ /dev/null
@@ -1,12 +0,0 @@
-#!/usr/bin/env node
-
-var ipfs = require('../src')('localhost', 5001)
-var files = process.argv.slice(2)
-
-ipfs.add(files, {recursive: true}, function (err, res) {
-  if (err || !res) return console.log(err)
-
-  for (var i = 0; i < res.length; i++) {
-    console.log('added', res[i].Hash, res[i].Name)
-  }
-})
diff --git a/examples/ls.js b/examples/ls.js
deleted file mode 100644
index 6006e8696..000000000
--- a/examples/ls.js
+++ /dev/null
@@ -1,18 +0,0 @@
-'use strict'
-
-var ipfs = require('../src')('localhost', 5001)
-
-var hash = ['QmdbHK6gMiecyjjSoPnfJg6iKMF7v6E2NkoBgGpmyCoevh']
-
-ipfs.ls(hash, function (err, res) {
-  if (err || !res) return console.log(err)
-
-  res.Objects.forEach(function (node) {
-    console.log(node.Hash)
-
-    console.log('Links [%d]', node.Links.length)
-    node.Links.forEach(function (link, i) {
-      console.log('[%d]', i, link)
-    })
-  })
-})
diff --git a/examples/version.js b/examples/version.js
deleted file mode 100644
index c69598525..000000000
--- a/examples/version.js
+++ /dev/null
@@ -1,8 +0,0 @@
-'use strict'
-
-var ipfs = require('../src')('localhost', 5001)
-
-ipfs.commands(function (err, res) {
-  if (err) throw err
-  console.log(res)
-})