Autocomplete suggestion endpoint doc

search-endpoint.md

@@ -823,6 +823,57 @@ The returned JSON response will be like:
 }
 ```
 
+## Autocomplete suggestions
+**/api/discover/suggest**
+
+This endpoint returns a list of terms from a the Solr search core suggest handler. This is configured in solrconfig.xml and, if using with existing metatavalues (as opposed to a flat file), discovery.cfg.
+
+The following parameters are required:
+
+* `dict`: The name of the dictionary / suggest component e.g. "subject" or "countries_file"
+* `q`: A string query (at least 3 characters) to match against autocomplete suggestions
+
+The response is JSON representation as returned by Solr, there are no addressable DSpace objects in the response so no further modelling is used by the REST API.
+
+This is currently used by some vocabularies in submission forms (see traditionalpagetwo subject field for an example) and can be used elsewhere in the frontend or integrated systems.
+
+Example response
+
+```
+{
+  "responseHeader": {
+    "status": 0,
+    "QTime": 11
+  },
+  "suggest": {
+    "subject": {
+      "test": {
+        "numFound": 1,
+        "suggestions": [
+          {
+            "term": "<b>Test/b> Subject",
+            "weight": 1,
+            "payload": ""
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+**/api/discover/suggest/build**
+
+This endpoint triggers a (re)build of a named or all dictionaries defined in Solr search core suggestion handler configuration.
+
+A preauthorize check limits this endpoint to site-wide administrators.
+
+An optional `dict` parameter can be passed to build a specific dictionary, if allowed by configuration. The parameter value should match the name of the solr "suggester" component and an allowed dictionary in DSpace configuration. See `dspace/solr/search/solrconfig.xml` and the `discovery.suggest.allowed-dictionaries` configuration property in `dspace/config/discovery.cfg`.
+
+If no `dict` parameter is parsed, all allowed dictionaries will be rebuilt.
+
+Solr suggest dictionaries do not track atomic updates to documents in the search core - they need to be fully rebuild to capture all changes made to underlying Solr documents in the search core. For this reason, it is recommended to rebuild dictionaries on startup and at regular intervals, and after deletion of sensitive metadata.
+
 ## Special configurations
 
 ### workspace