4 files changed, 24 insertions, 1 deletions
diff --git a/doc/api/README.md b/doc/api/README.md
index ee24449343a..517a9fae6f6 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -96,13 +96,30 @@ curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: username" "h
 curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: 23" "http://example.com/api/v3/projects"
 ```
 
-#### Pagination
+## Pagination
 
 When listing resources you can pass the following parameters:
 
 + `page` (default: `1`) - page number
 + `per_page` (default: `20`, max: `100`) - number of items to list per page
 
+## id vs iid
+
+When you work with API you may notice two similar fields in api entites: id and iid. 
+The main difference between them is scope. Example: 
+
+Issue 
+  id: 46
+  iid: 5
+
+* id - is uniq across all Issues table. It used for any api calls. 
+* iid - is uniq only in scope of single project. When you browse issues or merge requests with Web UI - you see iid. 
+
+So if you want to get issue with api you use `http://host/api/v3/.../issues/:id.json`
+But when you want to create a link to web page - use  `http:://host/project/issues/:iid.json`
+
+
+
 ## Contents
 
 + [Users](users.md)
diff --git a/doc/api/issues.md b/doc/api/issues.md
index 9082cbb50ba..ef37940faf0 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -11,6 +11,7 @@ GET /issues
 [
   {
     "id": 43,
+    "iid": 3,
     "project_id": 8,
     "title": "4xx/5xx pages",
     "description": "",
@@ -31,6 +32,7 @@ GET /issues
   },
   {
     "id": 42,
+    "iid": 4,
     "project_id": 8,
     "title": "Add user settings",
     "description": "",
@@ -100,6 +102,7 @@ Parameters:
 ```json
 {
   "id": 42,
+  "iid": 3,
   "project_id": 8,
   "title": "Add user settings",
   "description": "",
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index dae12f03ef5..2ddaea5a584 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -15,6 +15,7 @@ Parameters:
 [
     {
         "id":1,
+        "iid":1,
         "target_branch":"master",
         "source_branch":"test1",
         "project_id":3,
@@ -59,6 +60,7 @@ Parameters:
 ```json
 {
     "id":1,
+    "iid":1,
     "target_branch":"master",
     "source_branch":"test1",
     "project_id":3,
diff --git a/doc/api/milestones.md b/doc/api/milestones.md
index 2bdca68351b..e899e28d219 100644
--- a/doc/api/milestones.md
+++ b/doc/api/milestones.md
@@ -10,6 +10,7 @@ GET /projects/:id/milestones
 [
   {
     "id":12,
+    "iid":3,
     "project_id":16,
     "title":"10.0",
     "description":"Version",