diff --git a/rest-api-spec/api/indices.optimize.json b/rest-api-spec/api/indices.optimize.json
index 312a8a006f2..8c0fec286a3 100644
--- a/rest-api-spec/api/indices.optimize.json
+++ b/rest-api-spec/api/indices.optimize.json
@@ -1,30 +1,46 @@
 {
   "indices.optimize": {
-    "documentation": "",
+    "documentation": "http://www.elasticsearch.org/guide/reference/api/admin-indices-optimize/",
     "methods": ["POST", "GET"],
     "url": {
       "path": "/_optimize",
       "paths": ["/_optimize", "/{index}/_optimize"],
       "parts": {
         "index": {
+          "type" : "list",
+          "required" : true,
+          "description" : "A comma-separated list of index names; use `_all` or empty string to perform the operation on all indices"
         }
       },
       "params": {
         "flush": {
+          "type" : "boolean",
+          "description" : "Specify whether the index should be flushed after performing the operation (default: true)"
         },
         "ignore_indices": {
-        },
-        "index": {
+          "type" : "enum",
+          "options" : ["none","missing"],
+          "default" : "none",
+          "description" : "When performed on multiple indices, allows to ignore `missing` ones"
         },
         "max_num_segments": {
+          "type" : "number",
+          "description" : "The number of segments the index should be merged into (default: dynamic)"
         },
         "only_expunge_deletes": {
+          "type" : "boolean",
+          "description" : "Specify whether the operation should only expunge deleted documents"
         },
         "operation_threading": {
+          "description" : "TODO: ?"
         },
         "refresh": {
+          "type" : "boolean",
+          "description" : "Specify whether the index should be refreshed after performing the operation (default: true)"
         },
         "wait_for_merge": {
+          "type" : "boolean",
+          "description" : "Specify whether the request should block until the merge process is finished (default: true)"
         }
       }
     },