diff --git a/markdown/definitions.md b/markdown/definitions.md
new file mode 100644
index 0000000..e69de29
diff --git a/markdown/overview.md b/markdown/overview.md
new file mode 100644
index 0000000..704b9d6
--- /dev/null
+++ b/markdown/overview.md
@@ -0,0 +1,24 @@
+# Mapzen Search API
+
+## Overview
+Searching the world with the Mapzen Search API, powered by [Pelias](https://github.com/pelias/pelias).
+----------
+
+Pelias is an experimental, open geocoder from [Mapzen](https://mapzen.com). It's built from the ground up as an open source and open data-friendly geocoder that's designed to operate on top of any new
+
+This documentation refers specifically to Mapzen Search (//TODO: do we want to call this Mapzen Place Search?), powered by Pelias, but is mirrored in the API of the [Pelias code](https://github.com/pelias/pelias).
+
+
+### Version information
+Version: 1.0.0
+
+### URI scheme
+Host: pelias.mapzen.com
+BasePath: /v1
+Schemes: HTTP, HTTPS
+
+### Produces
+
+* application/vnd.geo+json
+
+
diff --git a/markdown/paths.md b/markdown/paths.md
new file mode 100644
index 0000000..d76d1d1
--- /dev/null
+++ b/markdown/paths.md
@@ -0,0 +1,124 @@
+## Paths
+### Fast response endpoint to provide an end-user suggestions of matching places as they're typing the search string. Returns 10 matching places. Intended for use while the user is typing a response. For searching a complete query (if autocomplete doesn't deliver a match), use the /search endpoint.
+```
+GET /autocomplete
+```
+
+#### Parameters
+|Type|Name|Description|Required|Schema|Default|
+|----|----|----|----|----|----|
+|QueryParameter|text|User's search string|true|string (string)||
+|QueryParameter|focus.point.lon|Focal point longitude. Ideally a user's device location, but can also be a focal point (like the center of their view). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lat`. Accepts only WGS84 longitutdes.|false|number (float)||
+|QueryParameter|focus.point.lat|Focal point latitude. Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lon`. Accepts only WGS84 latitudes.|false|number (float)||
+
+
+#### Responses
+|HTTP Code|Description|Schema|
+|----|----|----|
+|200|A GeoJSON FeatureCollection array of geocoded places.|No Content|
+|400|Invalid request. Check that you are passing along valid parameters without conflicting options.|No Content|
+
+
+#### Tags
+
+* search
+* forward geocoding
+
+### Retrieves the full GeoJSON record for a given place. ID determined from the results of a `/search`, `/autocomplete`, or `/reverse` response.
+```
+GET /place
+```
+
+#### Parameters
+|Type|Name|Description|Required|Schema|Default|
+|----|----|----|----|----|----|
+|QueryParameter|ids|Place ID from Mapzen Search.|false|string (string)||
+
+
+#### Responses
+|HTTP Code|Description|Schema|
+|----|----|----|
+|200|ok|No Content|
+
+
+### Searches for the name of a place based on a lon/lat location. Used for address reverse geocoding, point of interest (POI) reverse geocoding, and reverse coarse geocoding.
+```
+GET /reverse
+```
+
+#### Parameters
+|Type|Name|Description|Required|Schema|Default|
+|----|----|----|----|----|----|
+|QueryParameter|point.lon|tk|true|number (float)||
+|QueryParameter|point.lat|tk|true|number (float)||
+|QueryParameter|boundary.circle.lon|tk|true|number (float)||
+|QueryParameter|boundary.circle.lat||false|number (float)||
+|QueryParameter|boundary.circle.radius|bounding circle radius (in KM).|false|number (float)||
+|QueryParameter|boundary.country|Limits search to only return matches within a specific country. Accepts 2 or 3 letter country codes based on ISO [Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) or [Alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) abbreviations.|false|string (string)||
+|QueryParameter|layers|tk|false|string||
+|QueryParameter|sources|tk|false|string||
+|QueryParameter|size||false|integer (int32)|10|
+
+
+#### Responses
+|HTTP Code|Description|Schema|
+|----|----|----|
+|200|GeoJSON FeatureCollection|No Content|
+
+
+### Geocodes a user's search query
+```
+GET /search
+```
+
+#### Parameters
+|Type|Name|Description|Required|Schema|Default|
+|----|----|----|----|----|----|
+|QueryParameter|text|User's search string|true|string (string)||
+|QueryParameter|focus.point.lon|Focal point longitude. Ideally a user's device location, but can also be a focal point. Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lat`. Accepts only WGS84 longitutdes.|false|number (float)||
+|QueryParameter|focus.point.lat|Focal point latitude. Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.point.lon`. Accepts only WGS84 latitudes.|false|number (float)||
+|QueryParameter|focus.viewport.min_lon|`focus.viewport` provides focus to user's viewable map area, using the viewable screen to calibrate results relevant for an end-user's area of interest based on what's on screen, where that is located, and the level of zoom.
+
+This parameter limits the user's viewport latitude (furthest bottom coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
+
+Accepts only WGS84 longitudes.
+|false|number (float)||
+|QueryParameter|focus.viewport.min_lat|This parameter limits the user's viewport longitude (furthest left coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
+Accepts only WGS84 latitudes.
+|false|number (float)||
+|QueryParameter|focus.viewport.max_lon|This parameter limits the user's viewport latitude (furthest right coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
+
+Accepts only WGS84 longitudes.
+|false|number (float)||
+|QueryParameter|focus.viewport.max_lat|This parameter limits the user's viewport longitude (furthest top coordinate). Used to provide results close to the user, while still finding good matches globally. Used in conjunction with `focus.viewport.min_lat`, `focus.viewport.min_lon`, `focus.viewport.max_lon`, and `focus.viewport.max_lat`.
+Accepts only WGS84 latitudes.
+|false|number (float)||
+|QueryParameter|layers|For more than one layer, accepts a comma separated list of valid layers. If any of those layers is invalid, the request will still be honored, but a warning will be noted in the `geocoding` block of the response.
+|false|string (string)||
+|QueryParameter|sources|tk|false|string||
+|QueryParameter|boundary.circle.lon|tk|false|number (float)||
+|QueryParameter|boundary.circle.lat|tk|false|number (float)||
+|QueryParameter|boundary.circle.radius|Maximum distance in meters from the centroid to search from. Forms the radius of a bounding circle.|false|number (float)||
+|QueryParameter|boundary.rect.min_lon||false|number (float)||
+|QueryParameter|boundary.rect.min_lat||false|number (float)||
+|QueryParameter|boundary.rect.max_lon||false|number (float)||
+|QueryParameter|boundary.rect.max_lat||false|number (float)||
+|QueryParameter|boundary.country|Limits search to only return matches within a specific country. Accepts 2 or 3 letter country codes based on ISO [Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) or [Alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes) abbreviations.
+|false|string (string)||
+|QueryParameter|size|Maximum number of possible matching places to be returned|false|integer (int32)|10|
+|QueryParameter|private|Option to disable query logging in Mapzen Search. Defaults to False.|false|boolean|false|
+
+
+#### Responses
+|HTTP Code|Description|Schema|
+|----|----|----|
+|200|a GeoJSON FeatureCollection array of geocoded places|No Content|
+|400|invalid request. Check that you are passing along valid parameters|No Content|
+|403|invalid API key. Register for a valid API key at the [Mapzen Developer Portal](https://mapzen.com/developer).|No Content|
+
+
+#### Tags
+
+* forward geocoding
+* search
+