diff --git a/docs/api-app.md b/docs/api-app.md
new file mode 100644
index 00000000..7768aa95
--- /dev/null
+++ b/docs/api-app.md
@@ -0,0 +1,256 @@
+## App object
+
+The App object represents a Loopback application.
+
+The App object extends [Express](http://expressjs.com/api.html#express) and supports [Express / Connect middleware](http://expressjs.com/api.html#middleware).  See [Express documentation](http://expressjs.com/api.html) for details.
+
+```js
+var loopback = require('loopback');
+var app = loopback();
+
+app.get('/', function(req, res){
+  res.send('hello world');
+});
+
+app.listen(3000);
+```
+    
+## Properties
+
+### models
+
+The `app.models` object has properties for all defined models. In the following example the `Product` and `CustomerReceipt` models are accessed using the `models` object.
+
+**NOTE:** you must call `app.boot()` to create the `app.models` object.
+
+```js
+var loopback = require('loopback');
+var app = loopback();
+app.boot({
+  dataSources: {
+    db: {connector: 'memory'}
+  }
+});
+app.model('product', {dataSource: 'db'});
+app.model('customer-receipt', {dataSource: 'db'});
+
+// available based on the given name
+var Product = app.models.Product;
+
+// also available as camelCase
+var product = app.models.product;
+
+// multi-word models are avaiable as pascal cased
+var CustomerReceipt = app.models.CustomerReceipt;
+
+// also available as camelCase
+var customerReceipt = app.models.customerReceipt;
+```
+
+## Methods 
+
+### app.boot([options])
+
+Initialize an application from an options object or a set of JSON and JavaScript files.
+
+**What happens during an app _boot_?**
+
+1. **DataSources** are created from an `options.dataSources` object or `datasources.json` in the current directory
+2. **Models** are created from an `options.models` object or `models.json` in the current directory
+3. Any JavaScript files in the `./models` directory are loaded with `require()`.
+
+**Options**
+
+ - `cwd` - _optional_ - the directory to use when loading JSON and JavaScript files
+ - `models` - _optional_ - an object containing `Model` definitions
+ - `dataSources` - _optional_ - an object containing `DataSource` definitions
+
+> **NOTE:** mixing `app.boot()` and `app.model(name, config)` in multiple files may result
+> in models being **undefined** due to race conditions. To avoid this when using `app.boot()`
+> make sure all models are passed as part of the `models` definition.
+
+<a name="model-definition"></a>
+**Model Definitions**
+
+The following is an example of an object containing two `Model` definitions: "location" and "inventory".
+
+```js
+{
+  "dealership": {
+    // a reference, by name, to a dataSource definition
+    "dataSource": "my-db",
+    // the options passed to Model.extend(name, properties, options)
+    "options": {
+      "relationships": {
+        "cars": {
+          "type": "hasMany",
+          "model": "Car",
+          "foreignKey": "dealerId"  
+        }
+      },
+      "remoteMethods": {
+        "nearby": {
+          "description": "Find nearby locations around the geo point",
+          "accepts": [
+            {"arg": "here", "type": "GeoPoint", "required": true, "description": "geo location (lat & lng)"}
+          ],
+          "returns": {"arg": "locations", "root": true}
+        }
+      }
+    },
+    // the properties passed to Model.extend(name, properties, options)
+    "properties": {
+      "id": {"id": true},
+      "name": "String",
+      "zip": "Number",
+      "address": "String"
+    }
+  },
+  "car": {
+    "dataSource": "my-db"
+    "properties": {
+      "id": {
+        "type": "String",
+        "required": true,
+        "id": true
+      },
+      "make": {
+        "type": "String",
+        "required": true
+      },
+      "model": {
+        "type": "String",
+        "required": true
+      }
+    }
+  }
+}
+```
+
+**Model definition properties**
+
+ - `dataSource` - **required** - a string containing the name of the data source definition to attach the `Model` to
+ - `options` - _optional_ - an object containing `Model` options
+ - `properties` _optional_ - an object defining the `Model` properties in [LoopBack Definition Language](http://docs.strongloop.com/loopback-datasource-juggler/#loopback-definition-language)
+
+**DataSource definition properties**
+ 
+ - `connector` - **required** - the name of the [connector](#working-with-data-sources-and-connectors)
+
+### model(name, definition)
+
+Define a `Model` and export it for use by remote clients.
+
+**definition**
+
+- `public` - **default: true** attach the `Model` to the app and export its methods to clients
+- `dataSource` - **required** the name of the `DataSource` to attach the `Model` to
+
+Example:
+
+```js
+// declare a DataSource
+app.boot({
+  dataSources: {
+    db: {
+      connector: 'mongodb',
+      url: 'mongodb://localhost:27015/my-database-name'
+    }
+  }
+});
+
+// describe a model
+var modelDefinition = {dataSource: 'db'};
+
+// create the model
+var Product = app.model('product', modelDefinition);
+
+// use the model api
+Product.create({name: 'pencil', price: 0.99}, console.log);
+```
+    
+**Note** - This will expose all [shared methods](#shared-methods) on the model.
+
+You may also export an existing `Model` by calling `app.model(Model)` like the example below.
+
+### models()
+
+Get the app's exported models. Only models defined using `app.model()` will show up in this list.
+
+```js
+var models = app.models();
+
+models.forEach(function (Model) {
+  console.log(Model.modelName); // color
+});
+```
+
+### docs(options)
+
+Enable swagger REST API documentation.
+
+**Options**
+
+ - `basePath` The basepath for your API - eg. 'http://localhost:3000'.
+
+**Example**
+
+```js
+// enable docs
+app.docs({basePath: 'http://localhost:3000'});
+```
+
+Run your app then navigate to [the API explorer](http://petstore.swagger.wordnik.com/). Enter your API basepath to view your generated docs.
+
+### app.use( router )
+
+Expose models over specified router.
+For example, to expose models over REST using the `loopback.rest` router:
+
+```js
+app.use(loopback.rest());
+```
+
+View generated REST documentation at [http://localhost:3000/_docs](http://localhost:3000/_docs).
+
+### Middleware
+
+LoopBack includes middleware similar to [Express / Connect middleware](http://expressjs.com/api.html#middleware).  
+
+
+
+#### loopback.token(options)
+    
+**Options**
+
+ - `cookies` - An `Array` of cookie names
+ - `headers` - An `Array` of header names
+ - `params` - An `Array` of param names
+
+Each array is used to add additional keys to find an `accessToken` for a `request`.
+
+The following example illustrates how to check for an `accessToken` in a custom cookie, query string parameter
+and header called `foo-auth`.
+
+```js
+app.use(loopback.token({
+  cookies: ['foo-auth'],
+  headers: ['foo-auth', 'X-Foo-Auth'],
+  cookies: ['foo-auth', 'foo_auth']
+}));
+```
+
+**Defaults**
+
+By default the following names will be checked. These names are appended to any optional names. They will always
+be checked, but any names specified will be checked first.
+
+```js
+  params.push('access_token');
+  headers.push('X-Access-Token');
+  headers.push('authorization');
+  cookies.push('access_token');
+  cookies.push('authorization');
+```
+
+> **NOTE:** The `loopback.token()` middleware will only check for [signed cookies](http://expressjs.com/api.html#req.signedCookies).