1 files changed, 44 insertions, 0 deletions
diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md
new file mode 100644
index 00000000000..7b3238441f6
--- /dev/null
+++ b/doc/api/namespaces.md
@@ -0,0 +1,44 @@
+# Namespaces
+
+## List namespaces
+
+Get a list of namespaces. (As user: my namespaces, as admin: all namespaces)
+
+```
+GET /namespaces
+```
+
+```json
+[
+  {
+    "id": 1,
+    "path": "user1",
+    "kind": "user"
+  },
+  {
+    "id": 2,
+    "path": "group1",
+    "kind": "group"
+  }
+]
+```
+
+You can search for namespaces by name or path, see below.
+
+## Search for namespace
+
+Get all namespaces that match your string in their name or path.
+
+```
+GET /namespaces?search=foobar
+```
+
+```json
+[
+  {
+    "id": 1,
+    "path": "user1",
+    "kind": "user"
+  }
+]
+```