diff --git a/API/README.md b/API/README.md
new file mode 100644
index 00000000..145de14d
--- /dev/null
+++ b/API/README.md
@@ -0,0 +1,3 @@
+# IPFS Core API
+
+This directory contains the description of the core IPFS API. In order to be considered "valid", an IPFS core implementation must expose the API described here. You can also use this loose spec as documentation for consuming the core APIs. Ther is an outline of the contents of that directory in the [API section of this repository's root README file](../README.md#api).
diff --git a/README.md b/README.md
index d21ba905..93d14e4b 100644
--- a/README.md
+++ b/README.md
@@ -17,54 +17,6 @@
   - [Node.js](#nodejs)
   - [Go](#go)
 - [API](#api)
-  - [bitswap (not spec'ed yet)](/API/bitswap)
-  - [block](/API/block)
-    - [`block.get`](/API/block#get)
-    - [`block.put`](/API/block#put)
-    - [`block.stat`](/API/block#stat)
-  - [bootstrap](/API/bootstrap)
-  - [config](/API/config)
-    - [`config.get`](/API/config#get)
-    - [`config.set`](/API/config#set)
-    - [`config.replace`](/API/config#replace)
-  - [dag](/API/dag)
-    - [`dag.put`](/API/dag#dagput)
-    - [`dag.get`](/API/dag#dagget)
-    - [`dag.tree`](/API/dag#dagtree)
-  - [dht (not spec'ed yet)](/API/dht)
-  - [files](/API/files)
-    - [`add`](/API/files#add)
-    - [`createAddStream`](/files#createaddstream)
-    - [`get`](/API/files#get)
-    - [`cat`](/API/files#cat)
-  - [generic operations](/API/generic)
-    - [`id`](/API/generic#id)
-    - [`version`](/API/generic#version)
-  - [object](/API/object)
-    - [`object.new`](/API/object#objectnew)
-    - [`object.put`](/API/object#objectput)
-    - [`object.get`](/API/object#objectget)
-    - [`object.data`](/API/object#objectdata)
-    - [`object.links`](/API/object#objectlinks)
-    - [`object.stat`](/API/object#objectstat)
-    - [`object.patch`](/API/object#objectpatch)
-      - [`object.patch.addLink`](/API/object#objectpatchaddlink)
-      - [`object.patch.rmLink`](/API/object#objectpatchrmlink)
-      - [`object.patch.appendData`](/API/object#objectpatchappenddata)
-      - [`object.patch.setData`](/API/object#objectpatchsetdata)
-  - [pin (not spec'ed yet)](/API/pin)
-  - [pubsub](/API/pubsub)
-    - [`pubsub.subscribe`](/API/pubsub#pubsubsubscribe)
-    - [`pubsub.unsubscribe`](/API/pubsub#pubsubunsubscribe)
-    - [`pubsub.publish`](/API/pubsub#pubsubpublish)
-    - [`pubsub.ls`](/API/pubsub#pubsubls)
-    - [`pubsub.peers`](/API/pubsub#pubsubpeers)
-  - [repo (not spec'ed yet)](/API/repo)
-  - [swarm](/API/swarm)
-    - [`swarm.addrs`](/API/swarm#addrs)
-    - [`swarm.connect`](/API/swarm#connect)
-    - [`swarm.disconnect`](/API/swarm#disconnect)
-    - [`swarm.peers`](/API/swarm#peers)
 - [Contribute](#contribute)
   - [Want to hack on IPFS?](#want-to-hack-on-ipfs)
 - [License](#license)
@@ -131,7 +83,56 @@ test.all(common)
 
 ## API
 
-A valid (read: that follows this interface) IPFS core implementation must expose the API described in [/API](/API).
+In order to be considered "valid", an IPFS core implementation  must expose the API described in [/API](/API). You can also use this loose spec as documentation for consuming the core APIs. Here is an outline of the contents of that directory:
+
+- [bitswap (not spec'ed yet)](/API/bitswap)
+- [block](/API/block)
+  - [`block.get`](/API/block#get)
+  - [`block.put`](/API/block#put)
+  - [`block.stat`](/API/block#stat)
+- [bootstrap](/API/bootstrap)
+- [config](/API/config)
+  - [`config.get`](/API/config#get)
+  - [`config.set`](/API/config#set)
+  - [`config.replace`](/API/config#replace)
+- [dag](/API/dag)
+  - [`dag.put`](/API/dag#dagput)
+  - [`dag.get`](/API/dag#dagget)
+  - [`dag.tree`](/API/dag#dagtree)
+- [dht (not spec'ed yet)](/API/dht)
+- [files](/API/files)
+  - [`add`](/API/files#add)
+  - [`createAddStream`](/files#createaddstream)
+  - [`get`](/API/files#get)
+  - [`cat`](/API/files#cat)
+- [generic operations](/API/generic)
+  - [`id`](/API/generic#id)
+  - [`version`](/API/generic#version)
+- [object](/API/object)
+  - [`object.new`](/API/object#objectnew)
+  - [`object.put`](/API/object#objectput)
+  - [`object.get`](/API/object#objectget)
+  - [`object.data`](/API/object#objectdata)
+  - [`object.links`](/API/object#objectlinks)
+  - [`object.stat`](/API/object#objectstat)
+  - [`object.patch`](/API/object#objectpatch)
+    - [`object.patch.addLink`](/API/object#objectpatchaddlink)
+    - [`object.patch.rmLink`](/API/object#objectpatchrmlink)
+    - [`object.patch.appendData`](/API/object#objectpatchappenddata)
+    - [`object.patch.setData`](/API/object#objectpatchsetdata)
+- [pin (not spec'ed yet)](/API/pin)
+- [pubsub](/API/pubsub)
+  - [`pubsub.subscribe`](/API/pubsub#pubsubsubscribe)
+  - [`pubsub.unsubscribe`](/API/pubsub#pubsubunsubscribe)
+  - [`pubsub.publish`](/API/pubsub#pubsubpublish)
+  - [`pubsub.ls`](/API/pubsub#pubsubls)
+  - [`pubsub.peers`](/API/pubsub#pubsubpeers)
+- [repo (not spec'ed yet)](/API/repo)
+- [swarm](/API/swarm)
+  - [`swarm.addrs`](/API/swarm#addrs)
+  - [`swarm.connect`](/API/swarm#connect)
+  - [`swarm.disconnect`](/API/swarm#disconnect)
+  - [`swarm.peers`](/API/swarm#peers)
 
 ## Contribute