diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 00000000..bfea91b9
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,209 @@
+# Puppeteer API
+
+- [class: Browser](#class-browser)
+    - [new Browser([options])](#new-browseroptions)
+    - [browser.newPage()](#browsernewpage)
+    - [browser.closePage()](#browserclosepage)
+    - [browser.version()](#browserversion)
+    - [browser.close()](#browserclose)
+- [class: Page](#class-page)
+    - [page.setBlockedURLs(patterns)](#pagesetblockedurlspatterns)
+    - [page.addScriptTag(url)](#pageaddscripttagurl)
+    - [page.injectFile(filePath)](#pageinjectfilefilepath)
+    - [page.setInPageCallback(name, callback)](#pagesetinpagecallbackname-callback)
+    - [page.setExtraHTTPHeaders(headers)](#pagesetextrahttpheadersheaders)
+    - [page.extraHTTPHeaders()](#pageextrahttpheaders)
+    - [page.setUserAgentOverride(userAgent)](#pagesetuseragentoverrideuseragent)
+    - [page.userAgentOverride()](#pageuseragentoverride)
+    - [page.handleDialog(accept, promptText)](#pagehandledialogaccept-prompttext)
+    - [page.url()](#pageurl)
+    - [page.setContent(html)](#pagesetcontenthtml)
+    - [page.navigate(url)](#pagenavigateurl)
+    - [page.setSize(size)](#pagesetsizesize)
+    - [page.size()](#pagesize)
+    - [page.evaluate(fun, args)](#pageevaluatefun-args)
+    - [page.evaluateAsync(fun, args)](#pageevaluateasyncfun-args)
+    - [page.evaluateOnInitialized(fun, args)](#pageevaluateoninitializedfun-args)
+    - [page.screenshot(type[, clipRect])](#pagescreenshottype-cliprect)
+    - [page.saveScreenshot(filePath[, clipRect])](#pagesavescreenshotfilepath-cliprect)
+    - [page.printToPDF(filePath[, options])](#pageprinttopdffilepath-options)
+    - [page.plainText()](#pageplaintext)
+    - [page.title()](#pagetitle)
+    - [page.close()](#pageclose)
+
+### class: Browser
+
+Browser manages a browser instance, creating it with a predefined
+settings, opening and closing pages. Instantiating Browser class does
+not necessarily result in launching browser; the instance will be launched when the need will arise.
+
+#### new Browser([options])
+
+- `options` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)  Set of configurable options to set on the browser. Can have the following fields:
+	- `headless` [<boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) Wether to run chromium in headless mode. Defaults to `true`.
+	- `remoteDebuggingPort` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) Specify a remote debugging port to open on chromium instance. Defaults to `9229`.
+	- `executablePath` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Path to a chromium executable to run instead of bundled chromium.
+	- `args` [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) Additional arguments to pass to the chromium instance. List of chromium flags could be found [here](http://peter.sh/experiments/chromium-command-line-switches/).
+
+#### browser.newPage()
+
+- returns: [<Promise<Page>>](http://todo)
+
+Create a new page in browser and returns a promise which gets resolved with a Page object.
+
+#### browser.closePage()
+
+- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise)
+
+#### browser.version()
+
+- returns: [<Promise<string>>]((https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type))
+
+#### browser.close()
+
+Closes chromium application with all the pages (if any were opened). The browser object itself is considered to be disposed and could not be used anymore.
+
+### class: Page
+
+Page provides interface to interact with a tab in a browser. Pages are created by browser:
+
+```javascript
+var browser = new Browser();
+browser.newPage().then(page => {
+	...
+});
+```
+Pages could be closed by `page.close()` method.
+
+#### page.setBlockedURLs(patterns)
+
+- `patterns` [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
+- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when blocked URLs have been successfully set.
+
+#### page.addScriptTag(url)
+
+- `url` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Url of a script to be added
+- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves as the script gets added and loads.
+
+#### page.injectFile(filePath)
+
+- `url` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Path to the javascript file to be injected into page.
+- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when file gets successfully evaluated in page.
+
+#### page.setInPageCallback(name, callback)
+
+- `url` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Name of the callback to be assigned on window object
+- `callback` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) Callback function which will be called in node.js
+- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when callback is successfully initialized
+
+#### page.setExtraHTTPHeaders(headers)
+
+- `headers` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Key-value set of additional http headers to be sent with every request.
+- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when additional headers are installed
+
+#### page.extraHTTPHeaders()
+
+- returns: [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Key-value set of additional http headers, which will be sent with every request.
+
+#### page.setUserAgentOverride(userAgent)
+
+- `userAgent` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Specific user agent to use in this page
+- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when the user agent is set.
+
+#### page.userAgentOverride()
+
+- returns: [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Returns user agent override, if any.
+
+#### page.handleDialog(accept, promptText)
+
+- `accept` [<boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) Wether accept or discard the dialog.
+- `promptText` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Optional text to put inside the text prompt.
+- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when the dialog is handled.
+
+#### page.url() 
+
+- returns: [<Promise<string>>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Promise which resolves with the current page url.
+
+#### page.setContent(html)
+
+- `html` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) HTML markup to assign to the page.
+- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when the content is successfully assigned.
+
+#### page.navigate(url)
+
+- `url` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) URL to navigate page to
+- returns: [<Promise<boolean>>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type) Promise which resolves when the page is navigated. The promise resolves to:
+	- `true` if the navigation succeeds and page's `load` event is fired.
+	- `false` if the navigation fails due to bad URL or SSL errors.
+
+#### page.setSize(size)
+
+- `size` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)  An object with two fields:
+	- `width` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) Specify page's width in pixels.
+	- `height` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) Specify page's height in pixels.
+- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when the dimensions are updated.
+
+#### page.size()
+
+- returns: [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)  An object with two fields:
+	- `width` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) Page's width in pixels.
+	- `height` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) Page's height in pixels.
+
+#### page.evaluate(fun, args)
+
+- `fun` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) Function to be evaluated in browser context
+- `args` [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) Arguments to pass to  `fun`
+- returns: [<Promise<Object>>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves to function return value
+
+#### page.evaluateAsync(fun, args)
+
+- `fun` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) Function to be evaluated in browser context
+- `args` [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) Arguments to pass to  `fun`
+- returns: [<Promise<Object>>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves to function
+
+#### page.evaluateOnInitialized(fun, args)
+
+- `fun` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) Function to be evaluated in browser context
+- `args` [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) Arguments to pass to  `fun`
+- returns: [<Promise<Object>>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves to function
+
+#### page.screenshot(type[, clipRect])
+
+- `type` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Specify screenshot type, could be either `jpeg` or `png`.
+- `clipRect` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) An object which specifies clipping region of the page. Should have the following fields:
+	- `x` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) x-coordinate of top-left corner of clip area
+	- `y` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) y-coordinate of top-left corner of clip area
+	- `width` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) width of clipping area
+	- `height` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) height of clipping area
+- returns: [<Promise<Buffer>>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves to buffer with captured screenshot
+
+#### page.saveScreenshot(filePath[, clipRect])
+
+- `filePath` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The file path to save image to. The screenshot type will be inferred from file extension
+- `clipRect` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Clip rect object which will be passed over to `page.screenshot` method.
+
+#### page.printToPDF(filePath[, options])
+
+- `filePath` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The file path to save image to. The screenshot type will be inferred from file extension
+- `options` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Options object which might have the following properties:
+	- `scale` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
+	- `displayHeaderFooter` [<boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+	- `printBackground` [<boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+	- `landscape` [<boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+	- `pageRanges` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+	- `format` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+	- `width` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
+	- `height` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
+- returns: [<Promise>](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promise which resolves when the PDF is saved.
+
+#### page.plainText()
+
+- returns: [<Promise<string>>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Returns page's inner text.
+
+#### page.title()
+
+- returns: [<Promise<string>>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Returns page's title.
+
+#### page.close()
+
+- returns: [<Promise>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Returns promise which resolves when page gets closed.
diff --git a/lib/Page.js b/lib/Page.js
index 30ca2b2a..2f8c9b3a 100644
--- a/lib/Page.js
+++ b/lib/Page.js
@@ -404,6 +404,7 @@ class Page extends EventEmitter {
     /**
      * @param {string} filePath
      * @param {!Object=} options
+     * @return {!Promise}
      */
     async printToPDF(filePath, options) {
         options = options || {};