diff --git a/doc/API.md b/doc/API.md
index ca8643f..5b0f0c4 100644
--- a/doc/API.md
+++ b/doc/API.md
@@ -1,78 +1,153 @@
 
 # Torque API
 
-Torque provides two kinds of visulizations. 
+Torque provides two kinds of visualizations. 
 
   - static: provides a way to create heatmap like visualizations (note for Andrew: fon). see ``TorqueLayer``
-  - dinamyc: animate points over a map (note for Andrew: Navy) see ``TiledTorqueLayer``
+  - dynamic: animate points over a map (note for Andrew: Navy) see ``TiledTorqueLayer``
 
 
 depending on the map provider you are using you need to use different layer type. Currently we provide layers for Google Maps and Leaflet.
 
 ## L.TorqueLayer(options)
 
-_Arguments_:
-    * options: object that contains the following attributes:
-        - user: cartodb username
-        - table: table name
-        - column: time column
-        - countby: aggregation per pixel, e.g: 'count(cartodb_id)',
-        - resolution: pixel resolution,
-        - is_time: true or false,
-        - steps: animation steps, e.g: 750,
-        - blendmode: canvas blend mode 'lighter'
+One of two core classes for the Torque library - it is used to create an animated torque layer with custom settings.
 
-## L.TorqueLayer.setKey(time: number)
+### Usage example
 
-_Arguments_
-    * time: set time to be displayed. Should be a number between [0, steps)
-## L.TorqueLayer.setCartoCSS(cartocss: string)
-_Arguments_
-    * cartocss: cartocss string that contains the point style. Torque does not support the full cartocss spec, only a small subset. 
-    ``value`` and ``zoom`` variables can be used. ``value`` is the value of aggregation (see ``countby`` constructor option). ``zoom`` is the current zoom being rendered
+```js
+  // initialize a torque layer that uses the CartoDB account details and SQL API to pull in data
+  var torqueLayer = new L.TorqueLayer({
+    user       : 'viz2',
+    table      : 'ow',
+    column     : 'date',
+    countby    : 'count(cartodb_id)',
+    resolution : 1,
+    is_time    : true,
+    steps      : 750,
+    pixel_size : 3,
+    blendmode  : 'lighter'
+  });
+```
 
-    ```
-    #layer {,
-      marker-fill: #662506;
-      marker-width: 20;
-      [value > 1] { marker-fill: #FEE391; }
-      [value > 2] { marker-fill: #FEC44F; }
-      [value > 3] { marker-fill: #FE9929; }
-      [value > 4] { marker-fill: #EC7014; }
-      [value > 5] { marker-fill: #CC4C02; }
-      [value > 6] { marker-fill: #993404; }
-      [value > 7] { marker-fill: #662506; }
-    }
-    ```
+### Options
 
+##### Provider options
+| Option    | type       | Default   | Description                            |
+|-----------|:-----------|:----------|:---------------------------------------|
+| provider  | string     | ```sql_api```   | Where is the data coming from? Alternative is 'url_template'|
+
+##### CartoDB data options
+| Option    | type       | Default   | Description                            |
+|-----------|:-----------|:----------|:---------------------------------------|
+| user      | string     | ```null```      | CartoDB account name. Found as, accountname.cartodb.com|
+| table     | string     | ```null```      | CartoDB table name where data is found |
+| column    | string     | ```null```      | CartoDB table's column name where date information is found (for dynamic type torque layer only)|
+| countby   | string     | ```null```      | The aggregation method to use for each pixel displayed where multiple data are found. Any valid PostgreSQL aggregate function |
+
+##### Dynamic/static options (Note for Santana: we can remove this option?)
+| Option    | type       | Default   | Description                            |
+|-----------|:-----------|:----------|:---------------------------------------|
+| is_time   | boolean    | ```true```   | Determines if the drawing is static or dynamic/animated |
+
+
+##### Display options
+| Option    | type       | Default   | Description                            |
+|-----------|:-----------|:----------|:---------------------------------------|
+| steps     | integer    | ```100```   | The number of steps to divide the data into for animated renderings |
+| resolution| numeric    | ```2```   | The x and y dimensions of each pixel as returned by the data|
+| blendmode | boolean    | ```null```   | The HTML5 Canvas composite operation for when multiple pixels overlap on the canvas |
+
+### Play options
+
+| Method    | options    | returns   | Description                            |
+|-----------|:-----------|:----------|:---------------------------------------|
+| ```setKey(time)``` | ```time numeric```    | ```this```   | sets the animation to the step indicated by ```time```, must be between 0 and N where N equals the number of steps|
+
+
+### Style options
+
+| Method    | options    | returns   | Description                            |
+|-----------|:-----------|:----------|:---------------------------------------|
+| ```setCartoCSS(cartocss)``` | ```cartocss string```    | ```this```   | style the map rendering using client-side cartocss | 
+
+The full CartoCSS spec is not supported by Torque but instead only a limited subset with some additions related to torque rendering. To see the full list of supported parameters, read the [Torque CartoCSS documentation here](CartoCSS.md). ``value`` and ``zoom`` variables can be used. ``value`` is the value of aggregation (see ``countby`` constructor option). ``zoom`` is the current zoom being rendered
+
+TorqueLayer currently expects ```marker``` styling
+
+##### CartoCSS Example
+
+This should be ```string``` encoded in Javascript
+
+```css
+#layer {,
+  marker-fill: #662506;
+  marker-width: 20;
+  [value > 1] { marker-fill: #FEE391; }
+  [value > 2] { marker-fill: #FEC44F; }
+  [value > 3] { marker-fill: #FE9929; }
+  [value > 4] { marker-fill: #EC7014; }
+  [value > 5] { marker-fill: #CC4C02; }
+  [value > 6] { marker-fill: #993404; }
+  [value > 7] { marker-fill: #662506; }
+}
+```
 
 ## L.TiledTorqueLayer(options)
-creates a static visualization
-_Arguments_:
-    * options:
-        - provider: 'url_template',
-        - url: tile template url e.g 'http://host.com/{z}/{x}/{y}.json', (note to Andrew: link here to the json data format)
-        - resolution: data resolution, e.g 4
+
+One of two core classes for the Torque library - it is used to create a static torque layer with client side filtering.
+
+##### Provider options
+| Option    | type       | Default   | Description                            |
+|-----------|:-----------|:----------|:---------------------------------------|
+| provider  | string     | ```sql_api```   | Where is the data coming from? Alternative is 'url_template'|
+| url  | string     | ```null```   | Tile template URL for fetching data e.g 'http://host.com/{z}/{x}/{y}.json'|
+
+##### CartoDB data options (Note to Santana: are these really here?)
+| Option    | type       | Default   | Description                            |
+|-----------|:-----------|:----------|:---------------------------------------|
+| user      | string     | ```null```      | CartoDB account name. Found as, accountname.cartodb.com|
+| table     | string     | ```null```      | CartoDB table name where data is found |
+| column    | string     | ```null```      | CartoDB table's column name where date information is found (for dynamic type torque layer only)|
+| countby   | string     | ```null```      | The aggregation method to use for each pixel displayed where multiple data are found. Any valid PostgreSQL aggregate function |
 
 
-## L.TiledTorqueLayer.setKey(keys: number|array)
-set keys to show, if it's an array all the keys in that array are accumulated
+##### Display options (Note to Santana: is blendmode here? or above even?)
+| Option    | type       | Default   | Description                            |
+|-----------|:-----------|:----------|:---------------------------------------|
+| resolution| numeric    | ```2```   | The x and y dimensions of each pixel as returned by the data|
+| blendmode | boolean    | ```null```   | The HTML5 Canvas composite operation for when multiple pixels overlap on the canvas |
 
-## L.TiledTorqueLayer.setCartoCSS(cartocss: string)
+### Filtering options
 
-``value`` and ``zoom`` variables can be used. only ``polygon-fill`` property is supported currently
+| Method    | options    | returns   | Description                            |
+|-----------|:-----------|:----------|:---------------------------------------|
+| ```setKey(keys)``` | ```keys numeric/array```    | ```this```   | which data categories to display on the map |
 
-_Example_:
-    ```
-    #layer {
-      polygon-fill: #FFFF00;
-      [value >= 10] { polygon-fill: #FFCC00; }
-      [value >= 100] { polygon-fill: #FF9900; }
-      [value >= 1000] { polygon-fill: #FF6600; }
-      [value >= 10000] { polygon-fill: #FF3300; }
-      [value > 100000] { polygon-fill: #C00; }
-    }
-    ```
+### Style options
+
+| Method    | options    | returns   | Description                            |
+|-----------|:-----------|:----------|:---------------------------------------|
+| ```setCartoCSS(cartocss)``` | ```cartocss string```    | ```this```   | style the map rendering using client-side cartocss | 
+
+``value`` and ``zoom`` variables can be used. only ``polygon-fill`` property is supported currently. To see the full list of supported parameters, read the [Torque CartoCSS documentation here](CartoCSS.md).
+
+TorqueLayer currently expects ```polygon``` styling
+
+##### CartoCSS Example
+
+This should be ```string``` encoded in Javascript
+
+```css
+#layer {
+  polygon-fill: #FFFF00;
+  [value >= 10] { polygon-fill: #FFCC00; }
+  [value >= 100] { polygon-fill: #FF9900; }
+  [value >= 1000] { polygon-fill: #FF6600; }
+  [value >= 10000] { polygon-fill: #FF3300; }
+  [value > 100000] { polygon-fill: #C00; }
+}
+```
 
 
 # gmaps layers (TODO)