From fcf1e3cd88e238a052cabb927e7d709112b9eb18 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yago=20Gonz=C3=A1lez?= <yagogonzalezg@gmail.com>
Date: Sat, 23 Jun 2018 16:28:00 +0200
Subject: [PATCH] api docs: Add guide for creating narrows.

Dramatically edited by tabbott to simplify the discussion and
duplication of content in our main search documentation.
---
 templates/zerver/api/construct-narrow.md      | 40 +++++++++++++++++++
 .../zerver/help/include/rest-endpoints.md     |  1 +
 2 files changed, 41 insertions(+)
 create mode 100644 templates/zerver/api/construct-narrow.md

diff --git a/templates/zerver/api/construct-narrow.md b/templates/zerver/api/construct-narrow.md
new file mode 100644
index 0000000000..37048b0340
--- /dev/null
+++ b/templates/zerver/api/construct-narrow.md
@@ -0,0 +1,40 @@
+# Construct a narrow
+
+A **narrow** is a set of filters for Zulip messages, that can be based
+on many different factors (like sender, stream, topic, search
+keywords, etc.).  the Zulip API (espec in the API for fetching messages).
+
+It is simplest top explain the algorithm for encoding a search as a
+narrow using a single example.  Consider the following search query
+(written as it would be entered in the Zulip webapp's search box).  It
+filters for messages sent on stream `announce`, not sent by
+`iago@zulip.com`, and containing the phrase `cool sunglasses`:
+
+```
+stream:announce -sender:iago@zulip.com cool sunglasses
+```
+
+This query would be JSON-encoded for use in the Zulip API using JSON
+as a list of simple objects, as follows:
+
+```
+[
+    {
+        "operator": "stream",
+        "operand": "announce"
+    },
+    {
+        "operator": "sender",
+        "operand": "iago@zulip.com",
+        "negated": true
+    },
+    {
+        "operator": "search",
+        "operand": "cool sunglasses"
+    }
+]
+```
+
+The full set of search/narrowing options supported by the Zulip API is
+documented in
+[the Zulip Help Center article on search](/help/search-for-messages).
diff --git a/templates/zerver/help/include/rest-endpoints.md b/templates/zerver/help/include/rest-endpoints.md
index aabc68bbc4..9be0cc83a6 100644
--- a/templates/zerver/help/include/rest-endpoints.md
+++ b/templates/zerver/help/include/rest-endpoints.md
@@ -4,6 +4,7 @@
 * [Update a message](/api/update-message)
 * [Render a message](/api/render-message)
 * [Upload a file](/api/upload-file)
+* [Construct a narrow](/api/construct-narrow)
 
 #### Streams