diff --git a/app/views/help/api.html.haml b/app/views/help/api.html.haml
index 4f7af193741..d7d7aed4232 100644
--- a/app/views/help/api.html.haml
+++ b/app/views/help/api.html.haml
@@ -63,3 +63,13 @@
   .file_content.wiki
     = preserve do
       = markdown File.read(Rails.root.join("doc", "api", "issues.md"))
+
+%br
+
+.file_holder#milestones
+  .file_title
+    %i.icon-file
+    Milestones
+  .file_content.wiki
+    = preserve do
+      = markdown File.read(Rails.root.join("doc", "api", "milestones.md"))
diff --git a/doc/api/README.md b/doc/api/README.md
index d32573aaa6b..53b4983ef47 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -29,3 +29,4 @@ The API uses JSON to serialize data. You don't need to specify `.json` at the en
 + [Projects](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/projects.md)
 + [Snippets](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/snippets.md)
 + [Issues](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/issues.md)
++ [Milestones](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/milestones.md)
diff --git a/doc/api/milestones.md b/doc/api/milestones.md
index 36a08fe44ba..f68d8eb7d58 100644
--- a/doc/api/milestones.md
+++ b/doc/api/milestones.md
@@ -34,10 +34,10 @@ POST /projects/:id/milestones
 Parameters:
 
 + `id` (required) - The ID or code name of a project
++ `milestone_id` (required) - The ID of a project milestone
 + `title` (required) - The title of an milestone
 + `description` (optional) - The description of the milestone
 + `due_date` (optional) - The due date of the milestone
-+ `closed` (optional) - The status of the milestone
 
 ## Edit milestone
 
diff --git a/lib/api/milestones.rb b/lib/api/milestones.rb
index 1ddcd1f8c89..f537b8e5bf2 100644
--- a/lib/api/milestones.rb
+++ b/lib/api/milestones.rb
@@ -33,15 +33,13 @@ module Gitlab
       #   title (required) - The title of the milestone
       #   description (optional) - The description of the milestone
       #   due_date (optional) - The due date of the milestone
-      #   closed (optional) - The status of the milestone
       # Example Request:
       #   POST /projects/:id/milestones
       post ":id/milestones" do
         @milestone = user_project.milestones.new(
           title: params[:title],
           description: params[:description],
-          due_date: params[:due_date],
-          closed: (params[:closed] || false)
+          due_date: params[:due_date]
         )
 
         if @milestone.save
@@ -55,6 +53,7 @@ module Gitlab
       #
       # Parameters:
       #   id (required) - The ID or code name of a project
+      #   milestone_id (required) - The ID of a project milestone
       #   title (optional) - The title of a milestone
       #   description (optional) - The description of a milestone
       #   due_date (optional) - The due date of a milestone