diff --git a/api-ref/source/dns-api-v2-tld.inc b/api-ref/source/dns-api-v2-tld.inc
new file mode 100644
index 000000000..6c306f4ae
--- /dev/null
+++ b/api-ref/source/dns-api-v2-tld.inc
@@ -0,0 +1,235 @@
+===
+Tld
+===
+
+Tld operations.
+
+
+Create Tld
+==========
+
+.. rest_method::  POST /v2/tlds
+
+Create a tld
+
+
+Normal response codes: 201
+Error response codes:409,405,404,403,401,400,503,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - name: tld_name
+   - description: tld_description
+
+Request Example
+---------------
+
+.. literalinclude:: samples/tlds/create-tld-request.json
+   :language: javascript
+
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - id: id
+   - name: tld_name
+   - description: tld_description
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/tlds/tld-response.json
+   :language: javascript
+
+
+Show Tld
+========
+
+.. rest_method::  GET /v2/tlds/{tld_id}
+
+Show a tld
+
+
+Normal response codes: 200
+Error response codes:405,404,403,401,400,503
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - tld_id: tld_id
+
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - id: id
+   - name: tld_name
+   - description: tld_description
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/tlds/tld-response.json
+   :language: javascript
+
+
+List Tlds
+=========
+
+.. rest_method::  GET /v2/tlds
+
+List the tlds associated with the Project
+
+
+Normal response codes: 200
+Error response codes:405,403,401,400,503
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - limit: limit
+   - marker: marker
+   - sort_dir: sort_dir
+   - sort_key: sort_key
+   - name: tld_name_filter
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - id: id
+   - name: tld_name
+   - description: tld_description
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/tlds/list-tlds-response.json
+   :language: javascript
+
+
+Update Tld
+==========
+
+.. rest_method::  PATCH /v2/tlds/{tld_id}
+
+Update a tld
+
+
+Normal response codes: 200
+Error response codes:405,404,403,401,400,503,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - tld_id: tld_id
+   - name: tld_name
+   - description: tld_description
+
+
+Request Example
+---------------
+
+.. literalinclude:: samples/tlds/update-tld-request.json
+   :language: javascript
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - id: id
+   - name: tld_name
+   - description: tld_description
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/tlds/update-tld-response.json
+   :language: javascript
+
+
+Delete Tld
+==========
+
+.. rest_method::  DELETE /v2/tlds/{tld_id}
+
+Delete a tld
+
+Normal response codes: 204
+Error response codes:405,404,403,401,400,503,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - tld_id: tld_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index e09ce178c..3fbb73eea 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -16,3 +16,4 @@
 .. include:: dns-api-v2-recordset.inc
 .. include:: dns-api-v2-pool.inc
 .. include:: dns-api-v2-limits.inc
+.. include:: dns-api-v2-tld.inc
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 0033530d0..e52925738 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -864,6 +864,55 @@ pool_attributes:
   required: true
   type: object
 
+
+#############################
+#      Tld Variables       #
+#############################
+
+
+# Header Variables
+###################
+
+# Path Variables
+#################
+
+tld_id:
+  description: |
+    ID for this tld
+  in: path
+  required: true
+  type: uuid
+
+# Query Variables
+##################
+
+# Filters
+
+tld_name_filter:
+  description: |
+    Filter results to only show tlds that have a name matching the filter
+  in: query
+  required: false
+  type: string
+
+
+# Body Variables
+#################
+
+tld_name:
+  description: |
+    Name for this tld
+  in: body
+  required: true
+  type: string
+
+tld_description:
+  description: |
+    Description for this tld
+  in: body
+  required: false
+  type: string
+
 #############################
 #      <ITEM> Variables       #
 #############################
diff --git a/api-ref/source/samples/tlds/create-tld-request.json b/api-ref/source/samples/tlds/create-tld-request.json
new file mode 100644
index 000000000..b0fba1c0b
--- /dev/null
+++ b/api-ref/source/samples/tlds/create-tld-request.json
@@ -0,0 +1,4 @@
+{
+    "name" : "com",
+    "description" : "tld description"
+}
diff --git a/api-ref/source/samples/tlds/list-tlds-response.json b/api-ref/source/samples/tlds/list-tlds-response.json
new file mode 100644
index 000000000..625ff16c0
--- /dev/null
+++ b/api-ref/source/samples/tlds/list-tlds-response.json
@@ -0,0 +1,26 @@
+{
+ "tlds": [
+   {
+     "name": "edu",
+     "links": {
+       "self": "http://192.168.11.182:9001/v2/tlds/a7bba387-712b-4b42-9368-4508642c6113"
+     },
+     "created_at": "2016-05-10 05:21:40",
+     "updated_at": null,
+     "id": "a7bba387-712b-4b42-9368-4508642c6113",
+     "description": "demo TLD"
+   },
+   {
+     "name": "com",
+     "links": {
+       "self": "http://192.168.11.182:9001/v2/tlds/cfee7486-7ce4-4851-9c38-7b0fe3d42ee9"
+     },
+     "created_at": "2016-05-18 05:07:58",
+     "updated_at": null,
+     "id": "cfee7486-7ce4-4851-9c38-7b0fe3d42ee9",
+     "description": "tld description"
+   }
+ ],
+ "links": {"self": "http://192.168.11.182:9001/v2/tlds"
+ }
+}
diff --git a/api-ref/source/samples/tlds/tld-response.json b/api-ref/source/samples/tlds/tld-response.json
new file mode 100644
index 000000000..b3414082a
--- /dev/null
+++ b/api-ref/source/samples/tlds/tld-response.json
@@ -0,0 +1,10 @@
+{
+   "name": "com",
+   "links": {
+     "self": "http://192.168.11.182:9001/v2/tlds/cfee7486-7ce4-4851-9c38-7b0fe3d42ee9"
+   },
+   "created_at": "2016-05-18 05:07:58",
+   "updated_at": null,
+   "id": "cfee7486-7ce4-4851-9c38-7b0fe3d42ee9",
+   "description": "tld description"
+}
diff --git a/api-ref/source/samples/tlds/update-tld-request.json b/api-ref/source/samples/tlds/update-tld-request.json
new file mode 100644
index 000000000..f6b962472
--- /dev/null
+++ b/api-ref/source/samples/tlds/update-tld-request.json
@@ -0,0 +1,4 @@
+{
+    "name" : "org",
+    "description" : "Updated the name from com to org"
+}
diff --git a/api-ref/source/samples/tlds/update-tld-response.json b/api-ref/source/samples/tlds/update-tld-response.json
new file mode 100644
index 000000000..d0c1937b7
--- /dev/null
+++ b/api-ref/source/samples/tlds/update-tld-response.json
@@ -0,0 +1,10 @@
+{
+  "name": "org",
+  "links": {
+    "self": "http://192.168.11.182:9001/v2/tlds/cfee7486-7ce4-4851-9c38-7b0fe3d42ee9"
+  },
+  "created_at": "2016-05-18 05:07:58",
+  "updated_at": "2016-05-18 05:45:24",
+  "id": "cfee7486-7ce4-4851-9c38-7b0fe3d42ee9",
+  "description": "Updated the name from com to org"
+}